TdhEnumerateProviderFieldInformation, fonction (tdh.h)

Article
08/26/2023

Récupère les métadonnées de champ spécifiées pour un fournisseur donné.

Syntaxe

TDHSTATUS TdhEnumerateProviderFieldInformation(
  [in]            LPGUID                    pGuid,
  [in]            EVENT_FIELD_TYPE          EventFieldType,
  [out, optional] PPROVIDER_FIELD_INFOARRAY pBuffer,
  [in, out]       ULONG                     *pBufferSize
);

Paramètres

[in] pGuid

GUID qui identifie le fournisseur dont vous souhaitez récupérer les informations.

[in] EventFieldType

Spécifiez le type de champ pour lequel vous souhaitez récupérer des informations. Pour connaître les valeurs possibles, consultez l’énumération EVENT_FIELD_TYPE .

[out, optional] pBuffer

Mémoire tampon allouée par l’utilisateur pour recevoir les informations de champ. Pour plus d’informations, consultez la structure PROVIDER_FIELD_INFOARRAY .

[in, out] pBufferSize

Taille, en octets, de la mémoire tampon pBuffer . Si la fonction réussit, ce paramètre reçoit la taille de la mémoire tampon utilisée. Si la mémoire tampon est trop petite, la fonction retourne ERROR_INSUFFICIENT_BUFFER et définit ce paramètre sur la taille de mémoire tampon requise. Si la taille de la mémoire tampon est égale à zéro à l’entrée, aucune donnée n’est retournée dans la mémoire tampon et ce paramètre reçoit la taille de mémoire tampon requise.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite. Sinon, cette fonction retourne l’un des codes de retour suivants en plus d’autres.

Code de retour	Description
ERROR_INSUFFICIENT_BUFFER	La taille de la mémoire tampon pBuffer est trop petite. Utilisez la taille de mémoire tampon requise définie dans pBufferSize pour allouer une nouvelle mémoire tampon.
ERROR_NOT_SUPPORTED	Le type de champ demandé n’est pas valide.
ERROR_NOT_FOUND	Le manifeste ou la classe MOF est introuvable ou ne contient pas d’informations pour le type de champ demandé.
ERROR_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
ERROR_FILE_NOT_FOUND	L’attribut resourceFileName dans le manifeste contient l’emplacement du binaire du fournisseur. Lorsque vous inscrivez le manifeste, l’emplacement est écrit dans le Registre. TDH n’a pas pu trouver le fichier binaire en fonction de l’emplacement inscrit.

Remarques

Cette fonction utilise le manifeste XML ou la classe MOF WMI pour récupérer les informations.

Exemples

L’exemple suivant montre comment énumérer les informations contenues dans le manifeste ou la classe MOF pour le champ demandé.

#include <windows.h>
#include <stdio.h>
#include <wmistr.h>
#include <evntrace.h>
#include <tdh.h>

#pragma comment(lib, "tdh.lib")

DWORD EnumFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType);

// GUID of the provider whose metadata you want to enumerate.

EXTERN_C __declspec(selectany) const GUID ProviderGuid = {0xd8909c24, 0x5be9, 0x4502, {0x98, 0xca, 0xab, 0x7b, 0xdc, 0x24, 0x89, 0x9d}};

void wmain(void)
{
    DWORD status = ERROR_SUCCESS;

    // Retrieve the keyword information.

    wprintf(L"Retrieve EventKeywordInformation\n");

    status = EnumFieldInfo((LPGUID)&ProviderGuid, EventKeywordInformation);
    if (ERROR_SUCCESS != status)
    {
        wprintf(L"Failed to retrieve EventKeywordInformation (%lu).\n\n", status);
    }
}

// Prints the information associated with the specified field type.
DWORD EnumFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType)
{
    DWORD status = ERROR_SUCCESS;
    PROVIDER_FIELD_INFOARRAY* penum = NULL;
    DWORD bufferSize = 0;

    // Retrieve the required buffer size. If the status is ERROR_INSUFFICIENT_BUFFER,
    // use bufferSize to allocate the buffer.

    status = TdhEnumerateProviderFieldInformation(pProvider, fieldType, penum, &bufferSize);
    if (ERROR_INSUFFICIENT_BUFFER == status)
    {
        penum = (PROVIDER_FIELD_INFOARRAY*) malloc(bufferSize);
        if (penum == NULL)
        {
            wprintf(L"Allocation failed (size=%lu).\n", bufferSize);
            status = ERROR_OUTOFMEMORY;
            goto cleanup;
        }

        // Retrieve the information for the field type.

        status = TdhEnumerateProviderFieldInformation(pProvider, fieldType, penum, &bufferSize);
    }

    // The first call can fail with ERROR_NOT_FOUND if none of the provider's event
    // descriptions contain the requested field type information.

    if (ERROR_SUCCESS == status)
    {
        // Loop through the list of field information and print the field's name,
        // description (if it exists), and value. 

        for (DWORD i = 0; i < penum->NumberOfElements; i++)
        {
            wprintf(L"Field name: %s\nDescription: %s\nValue: %I64u\n\n",
                (PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].NameOffset),
                (penum->FieldInfoArray[i].DescriptionOffset) ? 
                    (PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].DescriptionOffset): L"",
                penum->FieldInfoArray[i].Value);
        }
    }
    else
    {
        if (ERROR_NOT_FOUND == status)
        {
            wprintf(L"Requested field type not found.\n");
        }
        else
        {
            wprintf(L"TdhEnumerateProviderFieldInformation failed with %lu.\n", status);
        }

        goto cleanup;
    }

cleanup:

    if (penum)
    {
        free(penum);
        penum = NULL;
    }

    return status;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	tdh.h
Bibliothèque	Tdh.lib
DLL	Tdh.dll

Voir aussi

TdhEnumerateProviders

TdhQueryProviderFieldInformation

Share via