{"id":187,"date":"2007-08-29T10:04:55","date_gmt":"2007-08-29T10:04:55","guid":{"rendered":"https:\/\/driverentry.com.br\/en\/2007\/08\/29\/using-fileobject-and-fscontext\/"},"modified":"2026-07-27T20:44:45","modified_gmt":"2026-07-27T20:44:45","slug":"using-fileobject-and-fscontext","status":"publish","type":"post","link":"https:\/\/driverentry.com.br\/en\/2007\/08\/29\/using-fileobject-and-fscontext\/","title":{"rendered":"Using FileObject and FsContext"},"content":{"rendered":"
\"\"<\/a><\/div>\n

Well, with some posts and a little patience to endure my jokes, we can construct a simple driver that responds to calls from applications. A call to CreateFile<\/a> function creates a connection between the application and device, returning a handle which will later be used to route reading\/writting requests to the device. If there are more calls to CreateFile<\/em> function, new handles will be returned. Like it happens with files, each handle has its own context. Suppose you open the same file twice so, you will get two handles with different contexts. A reading of 100 bytes from the first handle would cause the file’s current location be different from the initial position. A new reading using the same handle would result on getting the next 100 bytes ahead of the ones already read. Now if you used the second handle, you would get the first 100 bytes of the file. That’s because each handle would keep different file locations. In this post, I will talk about how to keep this context between the different opened handles for your device.<\/p>\n

The issue in practice<\/h3>\n

Not long ago, in one of my posts<\/a>, I gave a basic driver example that implements a linked list of buffers<\/em> that were written to the device. The same buffers<\/em> are obtained from further reads to the same device. This post will be based on this sample driver to make the tests and suggested modifications. The driver’s string list was implemented as a single global variable. If there is a single list, the various handles gotten from the applications will manipulate this same list.<\/p>\n

Remember that the test program writes the strings, that were typed in a console at the device until an empty one is supplied. When this occurs, the application starts reading and displaying the results at the screen. Thus, the same provided string sequence should be displayed. To reproduce the problem, follow the steps below with the test driver already installed:<\/p>\n

    \n
  1. Open up a Prompt<\/em> window and execute a test program instance.<\/li>\n
  2. Enter the string sequence that goes from “111”, “222” until “555”, but don’t enter the empty one yet.<\/li>\n
  3. Open up a new Prompt<\/em> window and execute another test program instance.<\/li>\n
  4. On this new window, enter the string sequence that goes from “666” until “999” and then, an empty one.<\/li>\n
  5. Go back to the previous instance and then, enter an empty string into the test program.<\/li>\n<\/ol>\n

    You should get an output as it is shown below. Note that the first test program instance has not read any string, despite having written several ones. These missing strings were got to the second test program instance.<\/p>\n

    \"\"<\/div>\n

    Separating lists<\/h3>\n

    Creating an algorithm able to separate these lists using the process identification could even work, but try to imagine that a single application could use two different libraries, which in turn, would use these lists. In this way, one library list would merge into the other library list, since both libraries are at the same process. To separate the context using various device openings, we use the FileObject<\/a> member of the current stack location<\/em>.<\/p>\n

    When an application calls the CreateFile<\/em> function, this request goes to the ObjectManager<\/em> which verifies the existence of the desired object, then checks whether the application has rights to obtain a handle to this object, and, if everything is agreed, the request reaches your driver in the form of an IRP<\/a> with its Major Function<\/em> as IRP_MJ_CREATE<\/a>. To get the FileObject<\/em> referring to this new connection being created, you need to do as shown at the code below.<\/p>\n

    \n
        \/\/-f--> Gets the FileObject referring to this list<\/span><\/pre>\n
        pStack = IoGetCurrentIrpStackLocation(pIrp);<\/pre>\n
        pFileObject = pStack->FileObject;<\/pre>\n<\/div>\n
    This or that list?<\/h3>\n
    All subsequent operations that come from the same object instance will come with the same FileObject<\/em>. This helps tracking the context of a certain device opening from the several ones that your driver receives.<\/p>\n
    So, all that I need to do is to create a list of FileObjects<\/em> and then link each one of them to a string list?<\/strong> The idea of linking the FileObject<\/em> to a structure that holds this context is so obvious that the system has already reserved a space into the FILE_OBJECT<\/strong> structure exclusively for this use.<\/p>\n
    \n
    typedef<\/span> struct<\/span> _FILE_OBJECT<\/pre>\n
    {<\/pre>\n
        CSHORT  Type;<\/pre>\n
        CSHORT  Size;<\/pre>\n
        PDEVICE_OBJECT  DeviceObject;<\/pre>\n
        PVPB  Vpb;<\/pre>\n
        PVOID  FsContext;<\/pre>\n
        PVOID  FsContext2;<\/pre>\n
        PSECTION_OBJECT_POINTERS  SectionObjectPointer;<\/pre>\n
        PVOID  PrivateCacheMap;<\/pre>\n
        NTSTATUS  FinalStatus;<\/pre>\n
        struct<\/span> _FILE_OBJECT  *RelatedFileObject;<\/pre>\n
        BOOLEAN  LockOperation;<\/pre>\n
        BOOLEAN  DeletePending;<\/pre>\n
        BOOLEAN  ReadAccess;<\/pre>\n
        BOOLEAN  WriteAccess;<\/pre>\n
        BOOLEAN  DeleteAccess;<\/pre>\n
        BOOLEAN  SharedRead;<\/pre>\n
        BOOLEAN  SharedWrite;<\/pre>\n
        BOOLEAN  SharedDelete;<\/pre>\n
        ULONG  Flags;<\/pre>\n
        UNICODE_STRING  FileName;<\/pre>\n
        LARGE_INTEGER  CurrentByteOffset;<\/pre>\n
        ULONG  Waiters;<\/pre>\n
        ULONG  Busy;<\/pre>\n
        PVOID  LastLock;<\/pre>\n
        KEVENT  Lock;<\/pre>\n
        KEVENT  Event;<\/pre>\n
        PIO_COMPLETION_CONTEXT  CompletionContext;<\/pre>\n
        KSPIN_LOCK  IrpListLock;<\/pre>\n
        LIST_ENTRY  IrpList;<\/pre>\n
        PVOID  FileObjectExtension;<\/pre>\n
     <\/pre>\n
    } FILE_OBJECT, *PFILE_OBJECT;<\/pre>\n<\/div>\n
    The FsContext<\/em> and FsContext2<\/em> fields are used for this purpose and unless you implement a filter, you can at ease use them. To make each device opening has its own list, it is necessary to store the head list address in one of these fields, as it is shown below at the new implementation of OnCreate<\/em>. The whole source code changes are available for downloading at the end of this post.<\/p>\n
    \n
    \/****<\/span><\/pre>\n
    ***     OnCreate<\/span><\/pre>\n
    **<\/span><\/pre>\n
    **      This routine is called whenever an application or driver<\/span><\/pre>\n
    **      tries to get a handle to the device we have created.<\/span><\/pre>\n
    *\/<\/span><\/pre>\n
     <\/pre>\n
    NTSTATUS<\/pre>\n
    OnCreate(IN PDEVICE_OBJECT  pDeviceObj,<\/pre>\n
             IN PIRP            pIrp)<\/pre>\n
    {<\/pre>\n
        NTSTATUS            nts = STATUS_SUCCESS;<\/pre>\n
        PBUFFER_LIST_HEAD   pListHead;<\/pre>\n
        PIO_STACK_LOCATION  pStack;<\/pre>\n
     <\/pre>\n
        \/\/-f--> A hello to the debugger...<\/span><\/pre>\n
        KdPrint((\"Opening EchoDevice...\\n\"<\/span>));<\/pre>\n
     <\/pre>\n
        \/\/-f--> Allocates the list head for this IRP_MJ_CREATE<\/span><\/pre>\n
        pListHead = (PBUFFER_LIST_HEAD) ExAllocatePoolWithTag(<\/pre>\n
            PagedPool,<\/pre>\n
            sizeof<\/span>(BUFFER_LIST_HEAD),<\/pre>\n
            ECHO_TAG);<\/pre>\n
     <\/pre>\n
        if<\/span> (pListHead)<\/pre>\n
        {<\/pre>\n
            \/\/-f--> Initializing the buffer list and its Mutex<\/span><\/pre>\n
            InitializeListHead(&pListHead->BufferList);<\/pre>\n
            KeInitializeMutex(&pListHead->Mutex, 0<\/span>);<\/pre>\n
     <\/pre>\n
            \/\/-f--> We store the context to the FileObject.<\/span><\/pre>\n
            pStack = IoGetCurrentIrpStackLocation(pIrp);<\/pre>\n
            pStack->FileObject->FsContext = pListHead;<\/pre>\n
        }<\/pre>\n
        else<\/span><\/pre>\n
            nts = STATUS_INSUFFICIENT_RESOURCES;<\/pre>\n
     <\/pre>\n
        \/\/-f--> Here we complete the IRP with success.<\/span><\/pre>\n
        pIrp->IoStatus.Status = nts;<\/pre>\n
        pIrp->IoStatus.Information = 0<\/span>;<\/pre>\n
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);<\/pre>\n
        return<\/span> nts;<\/pre>\n
    }<\/pre>\n<\/div>\n
    Is a FileObject equivalent to a Handle?<\/h3>\n
    No. Initially we have a handle for each FileObject<\/em>, but the number of handles to a FileObject<\/em> increases as their handles are duplicated. When the CreateFile <\/em>function is called, your driver receives an IRP_MJ_CREATE<\/strong>; however your driver is not alerted when someone calls the DuplicateHandle<\/a> function. Thus, each handle points to an object but an object can be pointed out by several handles.<\/p>\n
    Who will clean this mess?<\/h3>\n
    When all references to a given FileObject<\/em> are released, your device will receive an IRP_MJ_CLOSE<\/a>. Let’s use this event to clean up any remaining strings on the list.<\/p>\n
    \n
    \/****<\/span><\/pre>\n
    ***     OnClose<\/span><\/pre>\n
    **<\/span><\/pre>\n
    **      I'll make it simple just saying that this routine is called, whenever<\/span><\/pre>\n
    **      an application or driver closes the handle which was previously opened.<\/span><\/pre>\n
    **      Actually, this does not happen exactly in this way. (postponed to a future post)<\/span><\/pre>\n
    *\/<\/span><\/pre>\n
     <\/pre>\n
    NTSTATUS<\/pre>\n
    OnClose(IN PDEVICE_OBJECT  pDeviceObj,<\/pre>\n
            IN PIRP            pIrp)<\/pre>\n
    {<\/pre>\n
        PBUFFER_LIST_HEAD   pListHead;<\/pre>\n
        PIO_STACK_LOCATION  pStack;<\/pre>\n
        PLIST_ENTRY         pEntry;<\/pre>\n
        PBUFFER_ENTRY       pBufferEntry;<\/pre>\n
     <\/pre>\n
        \/\/-f--> A hello to the debugger...<\/span><\/pre>\n
        KdPrint((\"Closing EchoDevice...\\n\"<\/span>));<\/pre>\n
     <\/pre>\n
        \/\/-f--> Retrieves the list referring to this FileObject.<\/span><\/pre>\n
        pStack = IoGetCurrentIrpStackLocation(pIrp);<\/pre>\n
        pListHead = (PBUFFER_LIST_HEAD)pStack->FileObject->FsContext;<\/pre>\n
     <\/pre>\n
        \/\/-f--> Here, we remove all the remaining nodes that were not read<\/span><\/pre>\n
        \/\/      by the application. That would happen if the application had called<\/span><\/pre>\n
        \/\/      WriteFile but not ReadFile.<\/span><\/pre>\n
        while<\/span>(!IsListEmpty(&pListHead->BufferList))<\/pre>\n
        {<\/pre>\n
            \/\/-f--> It takes the first node from the list.<\/span><\/pre>\n
     <\/pre>\n
            pEntry = RemoveHeadList(&pListHead->BufferList);<\/pre>\n
     <\/pre>\n
            \/\/-f--> Retrieves the base address from the node<\/span><\/pre>\n
            pBufferEntry = CONTAINING_RECORD(pEntry, BUFFER_ENTRY, Entry);<\/pre>\n
     <\/pre>\n
            \/\/-f--> Finally releases the memory used by<\/span><\/pre>\n
            \/\/      that node.<\/span><\/pre>\n
            ExFreePool(pBufferEntry);<\/pre>\n
        }<\/pre>\n
     <\/pre>\n
        \/\/-f--> Releases the memory used by the head list.<\/span><\/pre>\n
     <\/pre>\n
        ExFreePool(pListHead);<\/pre>\n
     <\/pre>\n
        \/\/-f--> Here, we complete the IRP with success.<\/span><\/pre>\n
        pIrp->IoStatus.Status = STATUS_SUCCESS;<\/pre>\n
        pIrp->IoStatus.Information = 0<\/span>;<\/pre>\n
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);<\/pre>\n
        return<\/span> STATUS_SUCCESS;<\/pre>\n
    }<\/pre>\n<\/div>\n
    When an application is terminated or even when it falls unwillingly, all those application handles are closed by the system. Thus, it is guaranteed that your driver will always receive the IRP_MJ_CLOSE<\/strong> related to the object that was released. Actually, there is a little story about IRP_MJ_CLEANUP<\/a> and IRP_MJ_CLOSE<\/strong> that we will let to the next time.<\/p>\n
    Once implemented the change, each opened handle will own list, unless the handle is duplicated. If we repeat the same sequence of the listed steps above to force the error, we will get the following output.<\/p>\n
    \"\"<\/div>\n
    In a future post, I’ll show you how to give names to the lists in order to allow different processes begin able to open the same list from a known name.<\/p>\n
    CYA! \ud83d\ude42<\/p>\n
    FileObjEcho.zip<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
    Well, with some posts and a little patience to endure my jokes, we can construct a simple driver that responds to calls from applications. A call to CreateFile function creates a connection between the application and device, returning a handle which will later be used to route reading\/writting requests to the device. If there are […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":""},"categories":[1],"tags":[],"class_list":["post-187","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/187","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/comments?post=187"}],"version-history":[{"count":3,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/187\/revisions"}],"predecessor-version":[{"id":302,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/187\/revisions\/302"}],"wp:attachment":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/media?parent=187"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/categories?post=187"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/tags?post=187"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}