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

Article
02/27/2024

Avertissement

UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.

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 :

Code de retour	Description
E_POINTER	Le pointeur pdwCountedFileNameLength a la valeur NULL.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Le nom de fichier compté n’est pas valide.
E_NOT_SUFFICIENT_BUFFER	La mémoire tampon vers laquelle pCountedFileName pointe est trop petite.

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 :

Le pilote appelle RetrieveCountedFileName avec le paramètre pCountedFileName défini sur NULL pour obtenir la longueur de mémoire tampon requise.
Le pilote alloue une mémoire tampon de la taille requise.
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

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Partager via