Función CryptEnumProvidersA (wincrypt.h)

Importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.

 

La función CryptEnumProviders recupera los primeros o siguientes proveedores de servicios criptográficos (CSP) disponibles. Usada en un bucle, esta función puede recuperar en secuencia todos los CSP disponibles en un equipo.

Los CSP posibles incluyen la versión 1.0 del proveedor criptográfico base de Microsoft y la versión 1.0 del proveedor criptográfico mejorado de Microsoft.

Sintaxis

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 del siguiente proveedor que se va a enumerar.

[in] pdwReserved

Reservado para uso futuro y debe ser NULL.

[in] dwFlags

Reservado para uso futuro y debe ser cero.

[out] pdwProvType

Dirección del valor DWORD que designa el tipo del proveedor enumerado.

[out] szProvName

Puntero a un búfer que recibe los datos del proveedor enumerado. Se trata de una cadena que incluye el carácter nulo de terminación.

Este parámetro puede ser NULL para establecer el tamaño del nombre con fines de asignación de memoria. Para obtener más información, vea Recuperar datos de longitud desconocida.

[in, out] pcbProvName

Puntero a un valor DWORD que especifica el tamaño, en bytes, del búfer al que apunta el parámetro pszProvName . Cuando la función devuelve, el valor DWORD contiene el número de bytes almacenados en el búfer.

Nota Al procesar los datos devueltos en el búfer, las aplicaciones deben usar el tamaño real de los datos devueltos. El tamaño real puede ser ligeramente menor que el tamaño del búfer especificado en la entrada. (En la entrada, los tamaños del búfer suelen especificarse lo suficientemente grandes como para asegurarse de que los datos de salida más grandes posibles se ajusten al búfer). En la salida, la variable a la que apunta este parámetro se actualiza para reflejar el tamaño real de los datos copiados en el búfer.

 

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por NTE se generan mediante el CSP en particular que se usa. Siguen algunos códigos de error posibles.

Código devuelto	Descripción
ERROR_MORE_DATA	El búfer pszProvName no era lo suficientemente grande como para contener el nombre del proveedor.
ERROR_NO_MORE_ITEMS	No hay más elementos que enumerar.
ERROR_NOT_ENOUGH_MEMORY	El sistema operativo se quedó sin memoria.
NTE_BAD_FLAGS	El parámetro dwFlags tiene un valor no reconocido.
NTE_FAIL	Algo estaba mal con el registro de tipos.

Comentarios

Esta función enumera los proveedores disponibles en un equipo. Los tipos de proveedor se pueden enumerar mediante CryptEnumProviderTypes.

Ejemplos

En el ejemplo siguiente se muestra un bucle que enumera todos los proveedores de servicios criptográficos disponibles. Para obtener otro ejemplo que usa la función CryptEnumProviders , vea Programa C de ejemplo: Enumeración de proveedores y tipos de proveedor de 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");
}

Nota

El encabezado wincrypt.h define CryptEnumProviders como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll

Consulte también

CryptEnumProviderTypes

Funciones del proveedor de servicios