Estructura OPENCARDNAMEA (winscard.h)
La estructura OPENCARDNAME contiene la información que usa la función GetOpenCardName para inicializar un cuadro de diálogo Seleccionar tarjeta inteligente. Se recomienda llamar a SCardUIDlgSelectCard con OPENCARDNAME_EX mediante una llamada a GetOpenCardName con OPENCARDNAME. OPENCARDNAME se proporciona por motivos de 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 utilizado para la comunicación con el administrador de recursos de tarjeta inteligente. Llame a SCardEstablishContext para establecer el contexto del administrador de recursos 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 terminar 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 terminar 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 lpstrCardNames .
rgguidInterfaces
Reservado para uso futuro. Se establece en NULL. Matriz de GUID que identifican las interfaces necesarias.
cguidInterfaces
Reservado para futuros. Se establece en NULL. Número de interfaces de la matriz rgguidInterfaces .
lpstrRdr
Si se encuentra la tarjeta, el búfer lpstrRdr contiene el nombre del lector que contiene la tarjeta ubicada. El búfer debe tener al menos 256 caracteres de longitud.
nMaxRdr
Tamaño, en bytes (versión ANSI) o caracteres (versión 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 búfer lpstrCard contiene el nombre de la tarjeta ubicada. El búfer debe tener al menos 256 caracteres de longitud.
nMaxCard
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 se devuelve el cuadro de diálogo, establece estas marcas para indicar la entrada del usuario. Este miembro puede ser una combinación de las marcas siguientes.
| Value | Significado |
|---|---|
|
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. |
|
Forzar ninguna presentación de la interfaz de usuario (UI) de la tarjeta de selección, independientemente del resultado de la búsqueda. |
|
Forzar la visualización de la interfaz de usuario 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 miembros dwShareMode y dwPreferredProtocols .
Si lpfnConnect es NULL y dwShareMode es distinto de cero, se realiza una llamada interna a SCardConnect que usa dwShareMode y dwPreferredProtocols como parámetros 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 debe realizar un procesamiento adicional para conectarse a la tarjeta, este puntero de función se establece en la función connect del usuario. Si la función connect se realiza correctamente, la tarjeta se deja conectada e inicializa 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 rutina de comprobación de la tarjeta del autor de la llamada. Si no se requiere ninguna comprobación especial de la tarjeta, este puntero es NULL.
Si la rutina verify rechaza la tarjeta, se devuelve FALSE y la tarjeta está desconectada, como se indica en lpfnDisconnect.
Si la rutina verify acepta la tarjeta, se devuelve TRUE . Cuando el usuario acepte 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
);
hCardHandle
Identificador de la tarjeta conectada (a través de una conexión de cuadro de diálogo interno o una devolución de llamada lpfnConnect ).
Comentarios
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 Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Encabezado | winscard.h |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de