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

Статья
02/23/2024

Функция BCryptEnumRegisteredProviders извлекает сведения о зарегистрированных поставщиках.

Синтаксис

NTSTATUS BCryptEnumRegisteredProviders(
  [in, out] ULONG            *pcbBuffer,
  [in, out] PCRYPT_PROVIDERS *ppBuffer
);

Параметры

[in, out] pcbBuffer

Указатель на значение ULONG , которое при входе содержит размер (в байтах) буфера, на который указывает параметр ppBuffer . При выходе это значение получает либо количество байтов, скопированных в буфер, либо требуемый размер буфера (в байтах).

Примечание Это общий размер (в байтах) всего буфера, а не только размер структуры CRYPT_PROVIDERS . Буфер должен содержать другие данные для поставщиков в дополнение к структуре CRYPT_PROVIDERS .

[in, out] ppBuffer

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

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

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

Если этот параметр является адресом указателя, отличного от NULL , эта функция копирует сведения о поставщике в этот буфер. Параметр pcbBuffer должен содержать размер (в байтах) всего буфера. Если буфер недостаточно велик для хранения всех сведений о поставщике, эта функция вернет STATUS_BUFFER_TOO_SMALL.

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

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

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

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

Во-первых, функция BCryptEnumRegisteredProviders выделяет память. Это достигается путем передачи адреса указателя NULL для параметра ppBuffer .
В следующем примере показано, как использовать функцию BCryptEnumRegisteredProviders для выделения памяти путем передачи адреса указателя NULL для параметра ppBuffer .
```
PCRYPT_PROVIDERS pBuffer = NULL;
BCryptEnumRegisteredProviders(/*...*/, &pBuffer);
```
Этот код выделяет память, необходимую для структуры CRYPT_PROVIDERS и связанных строк. Если функция BCryptEnumRegisteredProviders используется таким образом, необходимо освободить память, когда она больше не нужна, передав ppBuffer в функцию BCryptFreeBuffer .
Второй способ заключается в выделении необходимой памяти самостоятельно. Для этого вызывается функция BCryptEnumRegisteredProviders со значением NULL для параметра ppBuffer . Функция BCryptEnumRegisteredProviders помещает в значение, указываемое параметром pcbBuffer , требуемый размер структуры CRYPT_PROVIDERS и всех строк в байтах. Затем выделяется необходимая память и передается адрес этого указателя буфера для параметра ppBuffer во втором вызове функции BCryptEnumRegisteredProviders .

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

Требования

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

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

BCryptFreeBuffer

CRYPT_PROVIDERS

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