IQueueCallbackCreate::OnCreateFile method (wudfddi.h)

Article
08/17/2022

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.

The OnCreateFile method is called to handle an open file request when an application opens a device through the Microsoft Win32 CreateFile function.

Syntax

void OnCreateFile(
  [in] IWDFIoQueue   *pWdfQueue,
  [in] IWDFIoRequest *pWDFRequest,
  [in] IWDFFile      *pWdfFileObject
);

Parameters

[in] pWdfQueue

A pointer to the IWDFIoQueue interface for the I/O queue object form which the request arrives.

[in] pWDFRequest

A pointer to the IWDFIoRequest interface for the I/O request object for the device.

[in] pWdfFileObject

A pointer to the IWDFFile interface for the file object that is associated with the device. This information is provided for convenience because the driver can call the IWDFIoRequest::GetCreateParameters method to obtain the file object.

Return value

None

Remarks

If the driver implements the IQueueCallbackCreate interface, the framework calls the OnCreateFile method when an application opens a device through the Win32 CreateFile function to perform an I/O operation, such as reading from or writing to a file.

A driver registers the IQueueCallbackCreate interface when the driver calls the IWDFDevice::CreateIoQueue method to create an I/O queue or to configure the default I/O queue.

A typical OnCreateFile method might call IWDFObject::AssignContext method on the file object to associate context with the file object, and then call IWDFIoRequest::Complete to complete the request.

A UMDF driver might be required to open registry keys or files while it impersonates a client that sends the I/O requests. From its implementation of the OnCreateFile method, the driver calls the IWDFIoRequest::Impersonate method to set a security impersonation level and to set the IImpersonateCallback::OnImpersonate method in which the driver handles the impersonation. To access necessary resources by using the credentials of the user, the framework calls the driver's OnImpersonate method. For any operations other than those that require impersonation, the framework calls driver methods that run under the default driver account. For more information about how UMDF and UMDF drivers handle impersonation, see Handling Impersonation.

Examples

This example is based on the WpdWudfSampleDriver sample, and is from the Queue.cpp file.

STDMETHODIMP_ (void) CQueue::OnCreateFile(
/*[in]*/ IWDFIoQueue* pQueue,
/*[in]*/ IWDFIoRequest* pRequest,
/*[in]*/ IWDFFile* pFileObject
)
{
  HRESULT hr = S_OK;
  ClientContext* pClientContext = new ClientContext ();

  // . . . Code omitted.

  if(pClientContext != NULL) {
    hr = pFileObject->AssignContext (this, (void*)pClientContext);

    // Release the client context if we cannot set it

    if(FAILED(hr)) {
      pClientContext->Release();
      pClientContext = NULL;
    }
  }
  else {
    hr = E_OUTOFMEMORY;
  }

  pRequest->Complete(hr);
}

Requirements

Requirement	Value
Target Platform	Windows
Header	wudfddi.h (include Wudfddi.h)

Share via