Función BCryptEnumContexts (bcrypt.h)

[BCryptEnumContexts está disponible para su uso en los sistemas operativos especificados en la sección Requisitos. Puede modificarse o no estar disponible en versiones posteriores.

La función BCryptEnumContexts obtiene los identificadores de los contextos de la tabla de configuración especificada.

Sintaxis

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

Parámetros

[in] dwTable

Identifica la tabla de configuración de la que se van a recuperar los contextos. Puede ser uno de los valores siguientes.

Valor	Significado
CRYPT_LOCAL	Recupere los contextos de la tabla de configuración del equipo local.
CRYPT_DOMAIN	Este valor no está disponible para su uso.

[in, out] pcbBuffer

La dirección de una variable de ULONG que, en la entrada, contiene el tamaño, en bytes, del búfer al que apunta ppBuffer. Si este tamaño no es lo suficientemente grande como para contener el conjunto de identificadores de contexto, se producirá un error en esta función con STATUS_BUFFER_TOO_SMALL.

Una vez que se devuelve esta función, este valor contiene el número de bytes que se copiaron en el búfer ppBuffer .

[in, out] ppBuffer

Dirección de un puntero a una estructura CRYPT_CONTEXTS que recibe el conjunto de contextos recuperados por esta función. El valor al que apunta el parámetro pcbBuffer contiene el tamaño de este búfer.

Si el valor al que apunta este parámetro es NULL, esta función asignará la memoria necesaria. Esta memoria debe liberarse cuando ya no sea necesaria pasando este puntero a la función BCryptFreeBuffer .

Si este parámetro es NULL, esta función colocará el tamaño necesario, en bytes, en la variable a la que apunta el parámetro pcbBuffer y devolverá STATUS_BUFFER_TOO_SMALL.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los posibles códigos de retorno se incluyen, entre otros, los siguientes.

Código devuelto	Descripción
STATUS_SUCCESS	La función se realizó correctamente.
STATUS_INVALID_PARAMETER	Uno o más parámetros no son válidos.
STATUS_NO_MEMORY	Error de asignación de memoria.
STATUS_BUFFER_TOO_SMALL	El parámetro ppBuffer no es NULL y el valor al que apunta el parámetro pcbBuffer no es lo suficientemente grande como para contener el conjunto de contextos.

Comentarios

Solo se puede llamar a BCryptEnumContexts en modo de usuario.

Ejemplos

En el ejemplo siguiente se muestra cómo usar la función BCryptEnumContexts para asignar la memoria para el búfer 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;
}

En el ejemplo siguiente se muestra cómo usar la función BCryptEnumContexts para asignar su propia memoria para el búfer 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;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	bcrypt.h
Library	Bcrypt.lib
Archivo DLL	Bcrypt.dll

Consulte también

BCryptFreeBuffer

CRYPT_CONTEXTS