Méthode IWDFFile2 ::RetrieveCountedFileName (wudfddi.h)

La méthode RetrieveCountedFileName récupère le nom de fichier total d’un fichier associé à un appareil.

Syntaxe

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

Paramètres

[out] pCountedFileName

Pointeur vers une mémoire tampon allouée par l’appelant. Cette mémoire tampon reçoit une chaîne de caractères null terminée qui représente le nom complet du fichier associé à l’appareil. Si le pointeur a la valeur NULL, RetrieveCountedFileName récupère uniquement la longueur de chaîne.

[in, out] pdwCountedFileNameLengthInChars

Pointeur vers une variable allouée par l’appelant. Lors de l’entrée, le pilote définit la variable sur la longueur, en caractères, de la mémoire tampon vers laquelle pdwCountedFileNameLengthInChars pointe. À la sortie, l’infrastructure définit la variable sur la longueur, en caractères, de la chaîne de caractères (y compris le caractère NULL de fin) qu’elle a placée dans la mémoire tampon. Si un nom de fichier compté n’existe pas, l’infrastructure définit la variable sur zéro.

Valeur retournée

RetrieveCountedFileName retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Cette méthode peut retourner l’une des autres valeurs dans Winerror.h.

Remarques

Un nom de fichier compté est une chaîne qui peut inclure des caractères NULL incorporés (« \0 ») en plus d’une valeur NULL de fin. Pour obtenir une chaîne de nom sans caractères NULL incorporés, les pilotes peuvent appeler IWDFFile ::RetrieveFileName.

En règle générale, un pilote appelle RetrieveCountedFileName deux fois, en procédant comme suit :

1. Le pilote appelle RetrieveCountedFileName avec le paramètre pCountedFileName défini sur NULL pour obtenir la longueur de mémoire tampon requise.
2. Le pilote alloue une mémoire tampon de la taille requise.
3. Le pilote appelle à nouveau RetrieveCountedFileName pour obtenir la chaîne de nom de fichier.

Exemples

L’exemple de code suivant obtient l’interface IWDFFile2 à partir de l’interface IWDFFile que reçoit la fonction de rappel IQueueCallbackCreate ::OnCreateFile d’un pilote. L’exemple appelle RetrieveCountedFileName deux fois ; une fois pour obtenir la longueur du nom de fichier et une fois pour récupérer la chaîne de nom de fichier.

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;
        }
    }
    ...

Configuration requise

Voir aussi

• IWDFFile2
• IWDFFile ::RetrieveFileName