functions.c

This the third edition of the Writing Device Drivers articles. The first article helped to simply ge

/**********************************************************************
 * 
 *  Toby Opferman
 *
 *  Driver Example
 *
 *  This example is for educational purposes only.  I license this source
 *  out for use in learning how to write a device driver.
 *
 *     Driver Functionality
 **********************************************************************/

#define _X86_ 

#include <wdm.h>
#include "example.h"
#include <public.h>


#define MIN(a,b) ((a) < (b) ? (a) : (b))

/**********************************************************************
 * Internal Functions
 **********************************************************************/
BOOLEAN Example_WriteData(PEXAMPLE_LIST pExampleList, PCHAR pData, UINT uiLength, UINT *pdwStringLength);
BOOLEAN Example_ReadData(PEXAMPLE_LIST pExampleList, PCHAR pData, UINT uiLength, UINT *pdwStringLength);
BOOLEAN Example_IsStringTerminated(PCHAR pString, UINT uiLength, UINT *pdwStringLength);
NTSTATUS Example_HandleSampleIoctl_DirectInIo(PIRP Irp, PIO_STACK_LOCATION pIoStackIrp, UINT *pdwDataWritten);
NTSTATUS Example_HandleSampleIoctl_DirectOutIo(PIRP Irp, PIO_STACK_LOCATION pIoStackIrp, UINT *pdwDataWritten);
NTSTATUS Example_HandleSampleIoctl_BufferedIo(PIRP Irp, PIO_STACK_LOCATION pIoStackIrp, UINT *pdwDataWritten);
NTSTATUS Example_HandleSampleIoctl_NeitherIo(PIRP Irp, PIO_STACK_LOCATION pIoStackIrp, UINT *pdwDataWritten);
NTSTATUS Example_CreatePipeContext(PEXAMPLE_DEVICE_CONTEXT pExampleDeviceContext, PFILE_OBJECT pFileObject);
NTSTATUS Example_ReleasePipeContext(PEXAMPLE_DEVICE_CONTEXT pExampleDeviceContext, PFILE_OBJECT pFileObject);

#pragma alloc_text(PAGE, Example_Create) 
#pragma alloc_text(PAGE, Example_Close) 
#pragma alloc_text(PAGE, Example_IoControl) 
#pragma alloc_text(PAGE, Example_ReadDirectIO)
#pragma alloc_text(PAGE, Example_ReadBufferedIO)
#pragma alloc_text(PAGE, Example_ReadNeither)
#pragma alloc_text(PAGE, Example_WriteDirectIO)
#pragma alloc_text(PAGE, Example_WriteBufferedIO)
#pragma alloc_text(PAGE, Example_WriteNeither)
#pragma alloc_text(PAGE, Example_UnSupportedFunction)
#pragma alloc_text(PAGE, Example_WriteData)
#pragma alloc_text(PAGE, Example_ReadData)
#pragma alloc_text(PAGE, Example_HandleSampleIoctl_DirectInIo)
#pragma alloc_text(PAGE, Example_HandleSampleIoctl_DirectOutIo)
#pragma alloc_text(PAGE, Example_HandleSampleIoctl_NeitherIo)
#pragma alloc_text(PAGE, Example_HandleSampleIoctl_DirectInIo)
#pragma alloc_text(PAGE, Example_CreatePipeContext)
#pragma alloc_text(PAGE, Example_ReleasePipeContext)
#pragma alloc_text(PAGE, Example_IsStringTerminated)
                                

/**********************************************************************
 * 
 *  Example_Create
 *
 *    This is called when an instance of this driver is created (CreateFile)
 *
 **********************************************************************/
NTSTATUS Example_Create(PDEVICE_OBJECT DeviceObject, PIRP Irp)
{
    NTSTATUS NtStatus = STATUS_SUCCESS;
    PIO_STACK_LOCATION pIoStackIrp = NULL;
    
    /*
     * Each time the IRP is passed down the driver stack a new stack location is added
     * specifying certain parameters for the IRP to the driver.
     */
    pIoStackIrp = IoGetCurrentIrpStackLocation(Irp);    


    DbgPrint("Example_Create Called \r\n");

    NtStatus = Example_CreatePipeContext((PEXAMPLE_DEVICE_CONTEXT)DeviceObject->DeviceExtension, pIoStackIrp->FileObject);

    /*
     * This does not always need to be completed in this manner.  The I/O Manager is friendly
     * and in the simple case (as this driver is implemented) the IRP will be completed
     * by IoCompleteRequest() and the Status will be set to the return value.
     *
     * What will not be set however is the "Information" field, it cannot be set to how many bytes
     * were read or written obviously because the I/O Manager does not know, only your device
     * driver does.
     *
     * There are cases where you will need to complete the IRP and set the status however
     * our simple driver does not require that.
     *
     * In the Write operation the "bytes written" is really only used as an informant to
     * the application.  The Read operation is a bit different.  For example, some types of buffering
     * it may not matter if you set the number of bytes read.  For example "Neither" you write
     * directly into the user mode buffer so the user mode gets the data even if you don't
     * tell it the amount.  However if you remember how buffered I/O works?  It makes a copy
     * in memory.  If the I/O manager doesn't know the size then it can't copy it back to the
     * user mode buffer.
     *  
     *
     * IO_NO_INCREMENT - What is this?  If an IRP request is taking a long time you may want to help
     * the scheduler to re-schedule the thread as soon as possible.  For example perhaps it issued
     * a network request and went to sleep.  Then on another thread the network request completes
     * You may want to use one of the pre-defined constants or your own to increment the priority of
     * that thread to be rescheduled being since it hasn't been scheduled in a while.
     *
     */

    Irp->IoStatus.Status = NtStatus;
    

    IoCompleteRequest(Irp, IO_NO_INCREMENT);
    return NtStatus;
}

/**********************************************************************
 * 
 *  Example_CreatePipeContext
 *
 *    This is called to create or find a pipe context
 *
 **********************************************************************/
NTSTATUS Example_CreatePipeContext(PEXAMPLE_DEVICE_CONTEXT pExampleDeviceContext, PFILE_OBJECT pFileObject)
{
    NTSTATUS NtStatus = STATUS_UNSUCCESSFUL;
    PEXAMPLE_LIST pExampleList = NULL;
    BOOLEAN bNeedsToCreate = FALSE;

    NtStatus = KeWaitForMutexObject(&pExampleDeviceContext->kListMutex, Executive, KernelMode, FALSE, NULL);

    if(NT_SUCCESS(NtStatus))
    {
         pExampleList = pExampleDeviceContext->pExampleList;
         bNeedsToCreate = TRUE;

         if(pExampleList)
         {
              do
              {   /*
                   * We want to use the unicode string that was used to open the driver to
                   * identify "pipe contexts" and match up applications that open the same name
                   * we do this by keeping a global list of all open instances in the device
                   * extension context.
                   * We then use reference counting so we only remove an instance from the list
                   * after all instances have been deleted.  We also put this in the FsContext
                   * of the IRP so all IRP's will be returned with this so we can easily use
                   * the context without searching for it.
                   */
                  if(RtlCompareUnicodeString(&pExampleList->usPipeName, &pFileObject->FileName, TRUE) == 0)
                  {
                      bNeedsToCreate = FALSE;
                      pExampleList->uiRefCount++;
                      pFileObject->FsContext = (PVOID)pExampleList;

                      NtStatus = STATUS_SUCCESS;
                  }
                  else
                  {
                      pExampleList = pExampleList->pNext;
                  }

              } while(pExampleList && bNeedsToCreate) ;
         }

         if(bNeedsToCreate)
         {
             pExampleList = (PEXAMPLE_LIST)ExAllocatePoolWithTag(NonPagedPool, sizeof(EXAMPLE_LIST), EXAMPLE_POOL_TAG);

             if(pExampleList)
             {
                 pExampleList->pNext = pExampleDeviceContext->pExampleList;
                 pExampleDeviceContext->pExampleList = pExampleList;

                 pExampleList->uiRefCount = 1;
                 pExampleList->usPipeName.Length = 0;
                 pExampleList->usPipeName.MaximumLength = sizeof(pExampleList->szwUnicodeString);
                 pExampleList->usPipeName.Buffer = pExampleList->szwUnicodeString;
                 pExampleList->uiStartIndex = 0;
                 pExampleList->uiStopIndex = 0;

                 KeInitializeMutex(&pExampleList->kInstanceBufferMutex, 0);

                 RtlCopyUnicodeString(&pExampleList->usPipeName, &pFileObject->FileName);
                 
                 pFileObject->FsContext = (PVOID)pExampleList;

                 NtStatus = STATUS_SUCCESS;
             }
             else
             {
                 NtStatus = STATUS_INSUFFICIENT_RESOURCES;
             }
         }

         KeReleaseMutex(&pExampleDeviceContext->kListMutex, FALSE);
    }
   
    
    return NtStatus;
}

/**********************************************************************
 * 
 *  Example_ReleasePipeContext
 *
 *    This is called to close a pipe context
 *
 **********************************************************************/
NTSTATUS Example_ReleasePipeContext(PEXAMPLE_DEVICE_CONTEXT pExampleDeviceContext, PFILE_OBJECT pFileObject)
{
    NTSTATUS NtStatus = STATUS_UNSUCCESSFUL;
    PEXAMPLE_LIST pExampleList = NULL, pExampleListFromIrp = (PEXAMPLE_LIST)pFileObject->FsContext;
    BOOLEAN bNotFound = TRUE;

    NtStatus = KeWaitForMutexObject(&pExampleDeviceContext->kListMutex, Executive, KernelMode, FALSE, NULL);

    if(NT_SUCCESS(NtStatus))
    {
         pExampleList = pExampleDeviceContext->pExampleList;

         if(pExampleListFromIrp)
         {
              if(pExampleList == pExampleListFromIrp)
              {
                 bNotFound = FALSE;
                 pExampleListFromIrp->uiRefCount--;
                          
                 if(pExampleListFromIrp->uiRefCount == 0)
                 {
                    pExampleDeviceContext->pExampleList = pExampleList->pNext;
                    ExFreePool(pExampleListFromIrp);

                 }

              }
              else
              {

                  do
                  {
                      if(pExampleListFromIrp == pExampleList->pNext)
                      {
                          bNotFound = FALSE;
                          pExampleListFromIrp->uiRefCount--;
                          
                          if(pExampleListFromIrp->uiRefCount == 0)
                          {
                             pExampleList->pNext = pExampleListFromIrp->pNext;
                             ExFreePool(pExampleListFromIrp);
                          }
    
                          NtStatus = STATUS_SUCCESS;
                      }
                      else
                      {
                          pExampleList = pExampleList->pNext;
                      }
    
                  } while(pExampleList && bNotFound == TRUE) ;
              }
         }

         if(bNotFound)
         {
             NtStatus = STATUS_UNSUCCESSFUL; /* Should Never Reach Here!!!!! */
         }



         KeReleaseMutex(&pExampleDeviceContext->kListMutex, FALSE);
    }
   
    
    return NtStatus;
}

/**********************************************************************
 * 
 *  Example_Close
 *
 *    This is called when an instance of this driver is closed (CloseHandle)
 *
 **********************************************************************/
NTSTATUS Example_Close(PDEVICE_OBJECT DeviceObject, PIRP Irp)
{
    NTSTATUS NtStatus = STATUS_SUCCESS;
    
    PIO_STACK_LOCATION pIoStackIrp = NULL;

    /*
     * Each time the IRP is passed down the driver stack a new stack location is added
     * specifying certain parameters for the IRP to the driver.
     */
    pIoStackIrp = IoGetCurrentIrpStackLocation(Irp);    


    DbgPrint("Example_Close Called \r\n");

    NtStatus = Example_ReleasePipeContext((PEXAMPLE_DEVICE_CONTEXT)DeviceObject->DeviceExtension, pIoStackIrp->FileObject);


    /*
     * This does not always need to be completed in this manner.  The I/O Manager is friendly
     * and in the simple case (as this driver is implemented) the IRP will be completed
     * by IoCompleteRequest() and the Status will be set to the return value.
     *
     * What will not be set however is the "Information" field, it cannot be set to how many bytes
     * were read or written obviously because the I/O Manager does not know, only your device
     * driver does.
     *
     * There are cases where you will need to complete the IRP and set the status however