BCryptEnumContexts, fonction (bcrypt.h)

Article
02/23/2024

[BCryptEnumContexts peut être utilisé dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il peut être modifié ou indisponible dans les versions suivantes.]

La fonction BCryptEnumContexts obtient les identificateurs des contextes dans la table de configuration spécifiée.

Syntaxe

NTSTATUS BCryptEnumContexts(
  [in]      ULONG           dwTable,
  [in, out] ULONG           *pcbBuffer,
  [in, out] PCRYPT_CONTEXTS *ppBuffer
);

Paramètres

[in] dwTable

Identifie la table de configuration à partir de laquelle récupérer les contextes. Il peut s’agir de l’une des valeurs suivantes.

Valeur	Signification
CRYPT_LOCAL	Récupérez les contextes de la table de configuration de l’ordinateur local.
CRYPT_DOMAIN	Cette valeur n’est pas disponible pour une utilisation.

[in, out] pcbBuffer

Adresse d’une variable ULONG qui, à l’entrée, contient la taille, en octets, de la mémoire tampon pointée par ppBuffer. Si cette taille n’est pas suffisamment grande pour contenir l’ensemble d’identificateurs de contexte, cette fonction échoue avec STATUS_BUFFER_TOO_SMALL.

Une fois cette fonction retournée, cette valeur contient le nombre d’octets qui ont été copiés dans la mémoire tampon ppBuffer .

[in, out] ppBuffer

Adresse d’un pointeur vers une structure de CRYPT_CONTEXTS qui reçoit l’ensemble des contextes récupérés par cette fonction. La valeur pointée par le paramètre pcbBuffer contient la taille de cette mémoire tampon.

Si la valeur pointée par ce paramètre est NULL, cette fonction alloue la mémoire requise. Cette mémoire doit être libérée quand elle n’est plus nécessaire en passant ce pointeur à la fonction BCryptFreeBuffer .

Si ce paramètre a la valeur NULL, cette fonction place la taille requise, en octets, dans la variable pointée par le paramètre pcbBuffer et retourne STATUS_BUFFER_TOO_SMALL.

Valeur retournée

Retourne un code status qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code de retour	Description
STATUS_SUCCESS	La fonction a réussi.
STATUS_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
STATUS_NO_MEMORY	Un échec d’allocation de mémoire s’est produit.
STATUS_BUFFER_TOO_SMALL	Le paramètre ppBuffer n’est pas NULL et la valeur pointée par le paramètre pcbBuffer n’est pas suffisamment grande pour contenir l’ensemble de contextes.

Remarques

BCryptEnumContexts peut être appelé uniquement en mode utilisateur.

Exemples

L’exemple suivant montre comment utiliser la fonction BCryptEnumContexts pour allouer la mémoire pour la mémoire tampon ppBuffer .

#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContexts_SystemAlloc()
{
    NTSTATUS status;
    ULONG uSize = 0;
    PCRYPT_CONTEXTS pContexts = NULL;
    
    // Get the contexts for the local computer. 
    // CNG allocates the memory.
    status = BCryptEnumContexts(CRYPT_LOCAL, &uSize, &pContexts);
    if(NT_SUCCESS(status))
    {
        // Enumerate the context identifiers.
        for(ULONG i = 0; i < pContexts->cContexts; i++)
        {
            wprintf(pContexts->rgpszContexts[i]);
            wprintf(L"\n");
        }

        // Free the buffer.
        BCryptFreeBuffer(pContexts);
    }

    return status;
}

L’exemple suivant montre comment utiliser la fonction BCryptEnumContexts pour allouer votre propre mémoire pour la mémoire tampon ppBuffer .

#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContexts_SelfAlloc()
{
    NTSTATUS status;
    ULONG uSize = 0;
    
    // Get the required size of the buffer.
    status = BCryptEnumContexts(CRYPT_LOCAL, &uSize, NULL);
    if(STATUS_BUFFER_TOO_SMALL == status)
    {
        // Allocate the buffer.
        PCRYPT_CONTEXTS pContexts = (PCRYPT_CONTEXTS)HeapAlloc(
            GetProcessHeap(), 
            HEAP_ZERO_MEMORY, 
            uSize);
        if(pContexts)
        {
            // Get the contexts for the local machine.
            status = BCryptEnumContexts(
                CRYPT_LOCAL, 
                &uSize, 
                &pContexts);
            if(NT_SUCCESS((status))
            {
                // Enumerate the context identifiers.
                for(ULONG i = 0; i < pContexts->cContexts; i++)
                {
                    wprintf(pContexts->rgpszContexts[i]);
                    wprintf(L"\n");
                }
            }

            // Free the buffer.
            HeapFree(GetProcessHeap(), 0, pContexts);
            pContexts = NULL;
        }
        else
        {
            status = STATUS_NO_MEMORY;
        }
    }

    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	bcrypt.h
Bibliothèque	Bcrypt.lib
DLL	Bcrypt.dll

Voir aussi

BCryptFreeBuffer

CRYPT_CONTEXTS

Share via