Funzione BCryptEnumContexts (bcrypt.h)

Articolo
03/14/2023

[BCryptEnumContexts è disponibile per l'uso nei sistemi operativi specificati nella sezione Requisiti. Potrebbe essere modificato o non disponibile nelle versioni successive.]

La funzione BCryptEnumContexts ottiene gli identificatori dei contesti nella tabella di configurazione specificata.

Sintassi

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

Parametri

[in] dwTable

Identifica la tabella di configurazione da cui recuperare i contesti. Può trattarsi di uno dei valori seguenti.

Valore	Significato
CRYPT_LOCAL	Recuperare i contesti dalla tabella di configurazione del computer locale.
CRYPT_DOMAIN	Questo valore non è disponibile per l'uso.

[in, out] pcbBuffer

L'indirizzo di una variabile ULONG che, nella voce, contiene le dimensioni, in byte, del buffer a cui punta ppBuffer. Se questa dimensione non è sufficientemente grande da contenere il set di identificatori di contesto, questa funzione avrà esito negativo con STATUS_BUFFER_TOO_SMALL.

Al termine della restituzione di questa funzione, questo valore contiene il numero di byte copiati nel buffer ppBuffer .

[in, out] ppBuffer

Indirizzo di un puntatore a una struttura CRYPT_CONTEXTS che riceve il set di contesti recuperati da questa funzione. Il valore a cui punta il parametro pcbBuffer contiene le dimensioni di questo buffer.

Se il valore a cui punta questo parametro è NULL, questa funzione allocherà la memoria richiesta. Questa memoria deve essere liberata quando non è più necessaria passando questo puntatore alla funzione BCryptFreeBuffer .

Se questo parametro è NULL, questa funzione inserisce le dimensioni richieste, in byte, nella variabile a cui punta il parametro pcbBuffer e restituisce STATUS_BUFFER_TOO_SMALL.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, a titolo esemplificativo, quanto segue.

Codice restituito	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.
STATUS_NO_MEMORY	Si è verificato un errore di allocazione della memoria.
STATUS_BUFFER_TOO_SMALL	Il parametro ppBuffer non è NULL e il valore a cui punta il parametro pcbBuffer non è sufficiente per contenere il set di contesti.

Commenti

BCryptEnumContexts può essere chiamato solo in modalità utente.

Esempio

L'esempio seguente illustra come usare la funzione BCryptEnumContexts per allocare la memoria per il buffer 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'esempio seguente illustra come usare la funzione BCryptEnumContexts per allocare la propria memoria per il buffer 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	bcrypt.h
Libreria	Bcrypt.lib
DLL	Bcrypt.dll

Vedi anche

BCryptFreeBuffer

CRYPT_CONTEXTS

Condividi tramite