IWDFFile2::RetrieveCountedFileName method

The RetrieveCountedFileName method retrieves the full counted file name for a file that is associated with a device.

Syntax


HRESULT RetrieveCountedFileName(
  [out]      WCHAR *pCountedFileName,
  [in, out]  DWORD *pdwCountedFileNameLength
);

Parameters

pCountedFileName [out]

A pointer to a caller-allocated buffer. This buffer receives a NULL-terminated character string that represents the full name of the file that is associated with the device. If the pointer is NULL, RetrieveCountedFileName retrieves only the string length.

pdwCountedFileNameLength [in, out]

A pointer to a caller-allocated variable. On input, the driver sets the variable to the length, in characters, of the buffer that pdwFileNameLengthInChars points to. On output, the framework sets the variable to the length, in characters, of the character string (including the terminating NULL character) that it placed in the buffer. If a counted file name does not exist, the framework sets the variable to zero.

Return value

RetrieveCountedFileName returns S_OK if the operation succeeds. Otherwise, the method might return one of the following values:

Return codeDescription
E_POINTER

The pdwCountedFileNameLength pointer is NULL.

HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)

The counted file name is invalid.

E_NOT_SUFFICIENT_BUFFER

The buffer that pCountedFileName points to is too small.

 

This method might return one of the other values that Winerror.h contains.

Remarks

A counted file name is a string that can include embedded NULL ('\0') characters in addition to a terminating NULL. To obtain a name string without embedded NULL characters, drivers can call IWDFFile::RetrieveFileName.

Typically, a driver calls RetrieveCountedFileName twice, using the following steps:

  1. The driver calls RetrieveCountedFileName with the pCountedFileName parameter set to NULL, to obtain the required buffer length.

  2. The driver allocates a buffer of the required size.

  3. The driver calls RetrieveCountedFileName again to obtain the file name string.

Examples

The following code example obtains the IWDFFile2 interface from the IWDFFile interface that a driver's IQueueCallbackCreate::OnCreateFile callback function receives. The example calls RetrieveCountedFileName twice--once to obtain the file name's length and once to retrieve the file name string.


VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in IWDFFile*  pWdfFileObject
    )
 ...
    IWDFFile2*  pWdfFileObject2 = NULL;
    WCHAR*  countedFileName = NULL;
    DWORD  countedFileNameCch = 0;
    HRESULT  hr = S_OK;
 
    //
    // Obtain IWDFFile2 interface from IWDFFile.
    //
    hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    //
    // Get length of counted filename.
    //
    hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
                                                  &countedFileNameCch);
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    if (countedFileNameCch != 0)
    {
        //
        // Allocate a buffer.
        //
        countedFileName = new WCHAR[countedFileNameCch];
        if (countedFileName == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto Done;
        }
        //
        // Get counted file name.
        //
        hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName, 
                                                      &countedFileNameCch);
        if (!SUCCEEDED(hr))
        {
            goto Done;
        }
    }
    ...

Requirements

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.9

Header

Wudfddi.h (include Wudfddi.h)

DLL

WUDFx.dll

See also

IWDFFile2
IWDFFile::RetrieveFileName

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft