Función SCardConnectA (winscard.h)

  • Artículo

La función SCardConnect establece una conexión (mediante un contexto específico del administrador de recursos) entre la aplicación que realiza la llamada y una tarjeta inteligente contenida en un lector específico. Si no existe ninguna tarjeta en el lector especificado, se devuelve un error.

Sintaxis

LONG SCardConnectA(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCSTR        szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Parámetros

[in] hContext

Identificador que identifica el contexto del administrador de recursos. El contexto del administrador de recursos se establece mediante una llamada anterior a SCardEstablishContext.

[in] szReader

Nombre del lector que contiene la tarjeta de destino.

[in] dwShareMode

Marca que indica si otras aplicaciones pueden formar conexiones a la tarjeta.

Valor Significado
SCARD_SHARE_SHARED
 Esta aplicación está dispuesta a compartir la tarjeta con otras aplicaciones.
SCARD_SHARE_EXCLUSIVE
 Esta aplicación no está dispuesta a compartir la tarjeta con otras aplicaciones.
SCARD_SHARE_DIRECT
 Esta aplicación asigna el lector para su uso privado y lo controlará directamente. No se permite el acceso a ninguna otra aplicación.

[in] dwPreferredProtocols

Máscara de bits de protocolos aceptables para la conexión. Los valores posibles se pueden combinar con la operación OR .

Valor Significado
SCARD_PROTOCOL_T0
 T=0 es un protocolo aceptable.
SCARD_PROTOCOL_T1
 T=1 es un protocolo aceptable.
0
 Este parámetro solo puede ser cero si dwShareMode está establecido en SCARD_SHARE_DIRECT. En este caso, los controladores no realizarán ninguna negociación de protocolo hasta que se envíe una directiva de control IOCTL_SMARTCARD_SET_PROTOCOL con SCardControl.

[out] phCard

Identificador que identifica la conexión a la tarjeta inteligente en el lector designado.

[out] pdwActiveProtocol

Marca que indica el protocolo activo establecido.

Valor Significado
SCARD_PROTOCOL_T0
 T=0 es el protocolo activo.
SCARD_PROTOCOL_T1
 T=1 es el protocolo activo.
SCARD_PROTOCOL_UNDEFINED
 SCARD_SHARE_DIRECT se ha especificado, de modo que no se haya producido ninguna negociación de protocolos. Es posible que no haya ninguna tarjeta en el lector.

Valor devuelto

Esta función devuelve valores diferentes en función de si se realiza correctamente o se produce un error.

Código devuelto Descripción
Success
 SCARD_S_SUCCESS.
Error
 Código de error. Para obtener más información, consulte Valores devueltos de tarjeta inteligente.
SCARD_E_NOT_READY
 El lector no pudo conectarse a la tarjeta.

Comentarios

La función SCardConnect es una función de acceso de lector y tarjeta inteligente. Para obtener más información sobre otras funciones de acceso, vea Funciones de acceso de tarjeta inteligente y lector.

Ejemplos

En el ejemplo siguiente se crea una conexión a un lector. En el ejemplo se supone que hContext es un identificador válido del tipo SCARDCONTEXT recibido de una llamada anterior a SCardEstablishContext.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Nota

El encabezado winscard.h define SCardConnect 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o 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 winscard.h
Library Winscard.lib
Archivo DLL Winscard.dll

Consulte también

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect