BCryptEnumContexts-Funktion (bcrypt.h)

Artikel
02/23/2024

[BCryptEnumContexts ist für die Verwendung in den im Abschnitt Anforderungen angegebenen Betriebssystemen verfügbar. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.]

Die BCryptEnumContexts-Funktion ruft die Bezeichner der Kontexte in der angegebenen Konfigurationstabelle ab.

Syntax

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

Parameter

[in] dwTable

Gibt die Konfigurationstabelle an, aus der die Kontexte abgerufen werden sollen. Dies kann einer der folgenden Werte sein.

Wert	Bedeutung
CRYPT_LOCAL	Rufen Sie die Kontexte aus der Konfigurationstabelle des lokalen Computers ab.
CRYPT_DOMAIN	Dieser Wert steht nicht zur Verwendung zur Verfügung.

[in, out] pcbBuffer

Die Adresse einer ULONG-Variablen , die bei einem Eintrag die Größe des Puffers in Byte enthält, auf den ppBuffer verweist. Wenn diese Größe nicht groß genug ist, um den Satz von Kontextbezeichnern zu enthalten, schlägt diese Funktion mit STATUS_BUFFER_TOO_SMALL fehl.

Nachdem diese Funktion zurückgegeben wurde, enthält dieser Wert die Anzahl der Bytes, die in den ppBuffer-Puffer kopiert wurden.

[in, out] ppBuffer

Die Adresse eines Zeigers auf eine CRYPT_CONTEXTS Struktur, die den Satz von Kontexten empfängt, die von dieser Funktion abgerufen werden. Der Wert, auf den der parameter pcbBuffer verweist, enthält die Größe dieses Puffers.

Wenn der Wert, auf den dieser Parameter verweist, NULL ist, ordnet diese Funktion den erforderlichen Arbeitsspeicher zu. Dieser Speicher muss freigegeben werden, wenn er nicht mehr benötigt wird, indem dieser Zeiger an die Funktion BCryptFreeBuffer übergeben wird.

Wenn dieser Parameter NULL ist, platziert diese Funktion die erforderliche Größe in Bytes in der Variablen, auf die der parameter pcbBuffer verweist, und gibt STATUS_BUFFER_TOO_SMALL zurück.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Funktion war erfolgreich.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
STATUS_NO_MEMORY	Ein Speicherbelegungsfehler ist aufgetreten.
STATUS_BUFFER_TOO_SMALL	Der ppBuffer-Parameter ist nicht NULL, und der Wert, auf den der parameter pcbBuffer verweist, ist nicht groß genug, um den Satz von Kontexten zu enthalten.

Hinweise

BCryptEnumContexts kann nur im Benutzermodus aufgerufen werden.

Beispiele

Das folgende Beispiel zeigt, wie Sie die BCryptEnumContexts-Funktion verwenden, um den Arbeitsspeicher für den ppBuffer-Puffer zuzuweisen.

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

Das folgende Beispiel zeigt, wie Sie die BCryptEnumContexts-Funktion verwenden, um Ihren eigenen Arbeitsspeicher für den ppBuffer-Puffer zuzuweisen.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	bcrypt.h
Bibliothek	Bcrypt.lib
DLL	Bcrypt.dll

Weitere Informationen

BCryptFreeBuffer

CRYPT_CONTEXTS

Freigeben über