Функция CryptEnumProvidersA (wincrypt.h)

Статья
11/20/2024

Важные этот API не рекомендуется. Новое и существующее программное обеспечение должно начинаться с API следующего поколения шифрования. Корпорация Майкрософт может удалить этот API в будущих выпусках.

Функция CryptEnumProviders извлекает первые или следующие доступные поставщики служб шифрования (CSPs). Используется в цикле, эта функция может получить последовательность всех поставщиков служб, доступных на компьютере.

Возможные поставщики УСЛУГ: поставщик шифрования Microsoft Base Cryptographic Provider версии 1.0 и Расширенный поставщик шифрования Майкрософт версии 1.0.

Синтаксис

BOOL CryptEnumProvidersA(
  [in]      DWORD dwIndex,
  [in]      DWORD *pdwReserved,
  [in]      DWORD dwFlags,
  [out]     DWORD *pdwProvType,
  [out]     LPSTR szProvName,
  [in, out] DWORD *pcbProvName
);

Параметры

[in] dwIndex

Индекс следующего поставщика для перечисления.

[in] pdwReserved

Зарезервировано для дальнейшего использования и должно быть NULL.

[in] dwFlags

Зарезервировано для будущего использования и должно быть равно нулю.

[out] pdwProvType

Адрес значения DWORD, указывающий тип перечисленного поставщика.

[out] szProvName

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

Этот параметр можно null, чтобы задать размер имени для целей выделения памяти. Дополнительные сведения см. в разделе получение данных неизвестной длины.

[in, out] pcbProvName

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

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

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

Если функция выполнена успешно, возвращаемое значение ненулевое (TRUE).

Если функция завершается ошибкой, возвращаемое значение равно нулю (FALSE). Для получения расширенных сведений об ошибке вызовите GetLastError.

Коды ошибок, предуставленные NTE, создаются конкретным используемым поставщиком служб CSP. Ниже приведены некоторые возможные коды ошибок.

Возвращаемый код	Описание
ERROR_MORE_DATA	Буфер pszProvName не был достаточно большим для хранения имени поставщика.
ERROR_NO_MORE_ITEMS	Перечисление элементов больше не существует.
ERROR_NOT_ENOUGH_MEMORY	Операционная система не хватает памяти.
NTE_BAD_FLAGS	Параметр dwFlags имеет нераспознанное значение.
NTE_FAIL	Что-то не так с регистрацией типов.

Замечания

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

Примеры

В следующем примере показан цикл, в котором перечислены все доступные поставщики криптографических служб. Другой пример использования функции CryptEnumProviders см. в примере программы C: перечисление поставщиков и типов поставщиков CSP.

#include <stdio.h>
#include <windows.h>
#include <Wincrypt.h>
#pragma comment(lib, "advapi32.lib")

void main()
{

    //---------------------------------------------------------------
    // Copyright (C) Microsoft.  All rights reserved.
    // Declare and initialize variables.

    DWORD       cbName;
    DWORD       dwType;
    DWORD       dwIndex;
    CHAR        *pszName = NULL; 

    // Print header lines for providers.
    printf("Listing Available Providers:\n");
    printf("Provider type\tProvider Name\n");
    printf("_____________\t__________________"
        "___________________\n");   

    //--------------------------------------------------------------- 
    // Loop through enumerating providers.
    dwIndex = 0;
    while(CryptEnumProviders(
           dwIndex,
           NULL,
           0,
           &dwType,
           NULL,
           &cbName
           ))
    {

        //-----------------------------------------------------------
        //  cbName returns the length of the name of the next 
        //  provider. Allocate memory in a buffer to retrieve 
        //  that name.

        if (!(pszName = (LPTSTR)LocalAlloc(LMEM_ZEROINIT, cbName)))
        {
           printf("ERROR - LocalAlloc failed\n");
           exit(1);
        }
        //-----------------------------------------------------------
        //  Get the provider name.
        if (CryptEnumProviders(
               dwIndex++,
               NULL,
               0,
               &dwType,
               pszName,
               &cbName
               ))
        {
            printf ("     %4.0d\t%s\n",dwType, pszName);
        }
        else
        {
            printf("ERROR - CryptEnumProviders failed.\n");
            exit(1);
        }
        LocalFree(pszName);

    } // End of while loop

    printf("\nProvider types and provider names "
        "have been listed.\n");
}

Заметка

Заголовок wincrypt.h определяет CryptEnumProviders в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	wincrypt.h
библиотеки	Advapi32.lib
DLL	Advapi32.dll

См. также

CryptEnumProviderTypes

функции поставщика услуг

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