Compartir a través de


Estructura OPENCARDNAMEA (winscard.h)

La estructura OPENCARDNAME contiene la información que usa la función GetOpenCardName para inicializar una tarjeta inteligente cuadro de diálogo Seleccionar tarjeta. Se recomienda llamar a SCardUIDlgSelectCard con OPENCARDNAME_EX mediante la llamada a GetOpenCardName con OPENCARDNAME. OPENCARDNAME se proporciona para la compatibilidad con versiones anteriores.

Sintaxis

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrRdr;
  DWORD          nMaxRdr;
  LPSTR          lpstrCard;
  DWORD          nMaxCard;
  LPCSTR         lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEA, *POPENCARDNAMEA, *LPOPENCARDNAMEA;

Miembros

dwStructSize

Especifica la longitud, en bytes, de la estructura. Este miembro no debe ser NULL.

hwndOwner

Ventana propietaria del cuadro de diálogo. Este miembro puede ser cualquier identificador de ventana válido o puede ser NULL para el escritorio predeterminado.

hSCardContext

Contexto usado para la comunicación con la tarjeta inteligente resource manager. Llame a SCardEstablishContext para establecer el de contexto de Resource Manager y SCardReleaseContext para liberarlo. Este miembro no debe ser NULL.

lpstrGroupNames

Puntero a un búfer que contiene cadenas de nombre de grupo terminadas en NULL. La última cadena del búfer debe finalizar con dos caracteres NULL. Cada cadena es el nombre de un grupo de tarjetas que se va a incluir en la búsqueda. Si lpstrGroupNames es null, se busca en el grupo predeterminado (Scard$DefaultReaders).

nMaxGroupNames

Número máximo de bytes (versión ANSI) o caracteres (versión Unicode) en la cadena lpstrGroupNames.

lpstrCardNames

Puntero a un búfer que contiene cadenas de nombre de tarjeta terminadas en NULL. La última cadena del búfer debe finalizar con dos caracteres NULL. Cada cadena es el nombre de una tarjeta que se va a ubicar.

nMaxCardNames

Número máximo de bytes (versión ANSI) o caracteres (versión Unicode) en la cadena de lpstrCardNames.

rgguidInterfaces

Reservado para uso futuro. Establezca en null. Matriz de GUID que identifican las interfaces necesarias.

cguidInterfaces

Reservado para futuros. Establezca en null. Número de interfaces de la matriz de rgguidInterfaces.

lpstrRdr

Si se encuentra la tarjeta, el lpstrRdr búfer contiene el nombre del lector que contiene la tarjeta ubicada. El búfer debe tener al menos 256 caracteres.

nMaxRdr

Tamaño, en bytes (versión ANSI) o caracteres (versión de Unicode), del búfer al que apunta lpstrRdr. Si el búfer es demasiado pequeño para contener la información del lector, GetOpenCardName devuelve SCARD_E_NO_MEMORY y el tamaño necesario del búfer al que apunta lpstrRdr.

lpstrCard

Si se encuentra la tarjeta, el lpstrCard búfer contiene el nombre de la tarjeta ubicada. El búfer debe tener al menos 256 caracteres.

nMaxCard

El tamaño, en bytes (versión ANSI) o caracteres (versión Unicode), del búfer al que apunta lpstrCard. Si el búfer es demasiado pequeño para contener la información de la tarjeta, GetOpenCardName devuelve SCARD_E_NO_MEMORY y el tamaño necesario del búfer en nMaxCard.

lpstrTitle

Puntero a una cadena que se va a colocar en la barra de título del cuadro de diálogo. Si este miembro es NULL, el sistema usa el título predeterminado "Seleccionar tarjeta:".

dwFlags

Un conjunto de marcas de bits que puede usar para inicializar el cuadro de diálogo. Cuando el cuadro de diálogo vuelve, establece estas marcas para indicar la entrada del usuario. Este miembro puede ser una combinación de las marcas siguientes.

Valor Significado
SC_DLG_MINIMAL_UI
Muestra el cuadro de diálogo solo si la aplicación que realiza la llamada no se encuentra y está disponible para su uso en un lector. Esto permite que se encuentre la tarjeta, conectada (ya sea a través del mecanismo del cuadro de diálogo interno o de las funciones de devolución de llamada del usuario) y se devuelva a la aplicación que realiza la llamada.
SC_DLG_NO_UI
Forzar ninguna presentación de la Seleccionar tarjetainterfaz de usuario (UI), independientemente del resultado de la búsqueda.
SC_DLG_FORCE_UI
Forzar visualización de la interfaz de usuario de Seleccionar tarjeta, independientemente del resultado de la búsqueda.

pvUserData

Puntero void a los datos del usuario. Este puntero se devuelve al autor de la llamada en las rutinas Connect, Check y Disconnect.

dwShareMode

Si lpfnConnect no es NULL , se omiten los dwShareMode y dwPreferredProtocols miembros.

Si lpfnConnect es NULL y dwShareMode es distinto de cero, a continuación, se realiza una llamada interna a SCardConnect que usa dwShareMode y dwPreferredProtocols como dwShareMode y dwPreferredProtocols. Si la conexión se realiza correctamente, hCardHandle se establece en el identificador devuelto por hSCardConnect.

Si lpfnConnect es NULL y dwShareMode es cero, el cuadro de diálogo devuelve hCardHandle como NULL.

dwPreferredProtocols

Se usa para la conexión interna como se describe en dwShareMode.

dwActiveProtocol

Devuelve el protocolo real en uso cuando el cuadro de diálogo realiza una conexión a una tarjeta.

lpfnConnect

Puntero a la rutina de conexión de tarjeta del autor de la llamada. Si el autor de la llamada necesita realizar un procesamiento adicional para conectarse a la tarjeta, este puntero de función se establece en la función connect para el usuario. Si la función connect se realiza correctamente, la tarjeta se deja conectada e inicializada y se devuelve el identificador de tarjeta.

El prototipo de la rutina de conexión es el siguiente.

Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains the 
                 //    possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);

lpfnCheck

Puntero a la tarjeta comprueba la rutina del autor de la llamada. Si no se requiere ninguna comprobación de tarjeta especial, este puntero se NULL.

Si la rutina de comprobación rechaza la tarjeta, se devuelve FALSE y la tarjeta está desconectada, como se indica en lpfnDisconnect.

Si la rutina de comprobación acepta la tarjeta, se devuelve TRUE. Cuando el usuario acepta la tarjeta, todas las demás tarjetas conectadas se desconectarán, como se indica en lpfnDisconnect, y esta tarjeta se devolverá como la tarjeta ubicada. La tarjeta ubicada permanecerá conectada.

El prototipo de la rutina de comprobación es el siguiente.

Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

lpfnDisconnect

Puntero a la rutina de desconexión de la tarjeta del autor de la llamada.

El prototipo de la rutina de desconexión es el siguiente.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

Nota Al usar lpfnConnect, lpfnChecky lpfnDisconnect, deben estar presentes los tres procedimientos de devolución de llamada. El uso de estas devoluciones de llamada permite comprobar aún más que la aplicación que realiza la llamada ha encontrado la tarjeta adecuada. Esta es la mejor manera de asegurarse de que se selecciona la tarjeta adecuada.
 

hCardHandle

Identificador de la tarjeta conectada (ya sea a través de una conexión de cuadro de diálogo interno o una devolución de llamada lpfnConnect).

Observaciones

Nota

El encabezado winscard.h define OPENCARDNAME 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido Windows Server 2003 [solo aplicaciones de escritorio]
encabezado de winscard.h

Consulte también

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard