Поделиться через

Функция BCryptEnumContexts (bcrypt.h)

  • Статья

[BCryptEnumContexts доступен для использования в операционных системах, указанных в разделе Требования. Он может быть изменен или недоступен в последующих версиях.]

Функция BCryptEnumContexts получает идентификаторы контекстов в указанной таблице конфигурации.

Синтаксис

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

Параметры

[in] dwTable

Определяет таблицу конфигурации, из которой извлекаются контексты. Это может быть одно из следующих значений.

Значение Значение
CRYPT_LOCAL
 Получите контексты из таблицы конфигурации локального компьютера.
CRYPT_DOMAIN
 Это значение недоступно для использования.

[in, out] pcbBuffer

Адрес переменной ULONG , которая при входе содержит размер буфера, на который указывает ppBuffer, в байтах. Если этот размер недостаточно велик для хранения набора идентификаторов контекста, эта функция завершится сбоем с STATUS_BUFFER_TOO_SMALL.

После возврата этой функции это значение содержит количество байтов, скопированных в буфер ppBuffer .

[in, out] ppBuffer

Адрес указателя на структуру CRYPT_CONTEXTS , которая получает набор контекстов, полученных этой функцией. Значение, на которое указывает параметр pcbBuffer , содержит размер этого буфера.

Если значение, на которое указывает этот параметр, равно NULL, эта функция выделяет необходимую память. Эта память должна быть освобождена, если она больше не нужна, путем передачи этого указателя в функцию BCryptFreeBuffer .

Если этот параметр имеет значение NULL, эта функция поместит необходимый размер в байтах в переменную, на которую указывает параметр pcbBuffer , и вернет STATUS_BUFFER_TOO_SMALL.

Возвращаемое значение

Возвращает код состояния, указывающий на успешное или неудачное выполнение функции.

Возможные коды возврата включают, помимо прочего, следующие.

Код возврата Описание
STATUS_SUCCESS
 Функция выполнена успешно.
STATUS_INVALID_PARAMETER
 Один или несколько параметров являются недопустимыми.
STATUS_NO_MEMORY
 Произошел сбой выделения памяти.
STATUS_BUFFER_TOO_SMALL
 Параметр ppBuffer не имеет значение NULL, а значение, на которое указывает параметр pcbBuffer , недостаточно велико для хранения набора контекстов.

Комментарии

BCryptEnumContexts можно вызывать только в пользовательском режиме.

Примеры

В следующем примере показано, как использовать функцию BCryptEnumContexts для выделения памяти для буфера 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;
}

В следующем примере показано, как использовать функцию BCryptEnumContexts для выделения собственной памяти для буфера 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;
}

Требования

Требование Значение
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2008 [только классические приложения]
Целевая платформа Windows
Header bcrypt.h
Библиотека Bcrypt.lib
DLL Bcrypt.dll

См. также раздел

BCryptFreeBuffer

CRYPT_CONTEXTS