Função CryptEnumProvidersA (wincrypt.h)

Artigo
11/20/2024

Importante essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração da Criptografia. Microsoft pode remover essa API em versões futuras.

A função CryptEnumProviders recupera o primeiro ou o próximo CSPs (provedor es de serviços criptográficos) disponíveis. Usada em um loop, essa função pode recuperar em sequência todos os CSPs disponíveis em um computador.

Os CSPs possíveis incluem o Microsoft Base Cryptographic Provider versão 1.0 e o Microsoft Enhanced Cryptographic Provider versão 1.0.

Sintaxe

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

Parâmetros

[in] dwIndex

Índice do próximo provedor a ser enumerado.

[in] pdwReserved

Reservado para uso futuro e deve ser NULL.

[in] dwFlags

Reservado para uso futuro e deve ser zero.

[out] pdwProvType

Endereço do DWORD valor que designa o tipo do provedor enumerado.

[out] szProvName

Um ponteiro para um buffer que recebe os dados do provedor enumerado. Essa é uma cadeia de caracteres que inclui o caractere nulo de terminação.

Esse parâmetro pode ser NULL para definir o tamanho do nome para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados dede comprimento desconhecido.

[in, out] pcbProvName

Um ponteiro para um valor DWORD especificando o tamanho, em bytes, do buffer apontado pelo parâmetro pszProvName. Quando a função retorna, o valor DWORD contém o número de bytes armazenados no buffer.

Observação Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis se ajustem ao buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero (TRUE).

Se a função falhar, o valor retornado será zero (false). Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro precedidos pelo NTE são gerados pelo CSP específico que está sendo usado. Alguns códigos de erro possíveis seguem.

Código de retorno	Descrição
ERROR_MORE_DATA	O buffer pszProvName não era grande o suficiente para manter o nome do provedor.
ERROR_NO_MORE_ITEMS	Não há mais itens para enumerar.
ERROR_NOT_ENOUGH_MEMORY	O sistema operacional ficou sem memória.
NTE_BAD_FLAGS	O parâmetro dwFlags tem um valor não reconhecido.
NTE_FAIL	Algo estava errado com o registro de tipo.

Observações

Essa função enumera os provedores disponíveis em um computador. Os tipos de provedor podem ser enumerados usando CryptEnumProviderTypes.

Exemplos

O exemplo a seguir mostra um loop listando todos os provedores de serviços criptográficos disponíveis. Para outro exemplo que usa a função CryptEnumProviders, consulte Exemplo de Programa C: Enumerando provedores CSP e tipos de provedor.

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

Nota

O cabeçalho wincrypt.h define CryptEnumProviders como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CryptEnumProviderTypes

Funções do provedor de serviços

Compartilhar via