estructura OPENCARD_SEARCH_CRITERIAA (winscard.h)

La estructura OPENCARD_SEARCH_CRITERIA se usa en la función SCardUIDlgSelectCard para reconocer tarjetas que cumplan los requisitos establecidos por el autor de la llamada. Sin embargo, puede llamar a SCardUIDlgSelectCard sin usar esta estructura.

Sintaxis

typedef struct {
  DWORD          dwStructSize;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAA, *POPENCARD_SEARCH_CRITERIAA, *LPOPENCARD_SEARCH_CRITERIAA;

Miembros

dwStructSize

Longitud, en bytes, de la estructura. No se debe 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.

rgguidInterfaces

Reservado para uso futuro. Matriz de GUID que identifica las interfaces necesarias. Establezca este miembro en NULL.

cguidInterfaces

Reservado para uso futuro. Número de interfaces de la matriz de rgguidInterfaces. Establezca este miembro en NULL.

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 lpstrGroupNames.

lpfnCheck

Puntero a la rutina de comprobación de la tarjeta 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 se desconectará la tarjeta. Si la rutina de comprobación acepta la tarjeta, se devuelve TRUE.

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

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

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 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
);

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 Cuando se usa 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. Sin embargo, cuando se usa un valor que no es NULL para lpfnCheck, ambas lpfnConnect y lpfnDisconnect no deben ser también se deben proporcionar NULL (y pvUserData) o dwShareMode y dwPreferredProtocols deben establecerse.

 

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, se realiza una llamada interna a SCardConnect que usa dwShareMode y dwPreferredProtocols como parámetro.

dwPreferredProtocols

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

Observaciones

Nota

El encabezado winscard.h define OPENCARD_SEARCH_CRITERIA 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

OPENCARDNAME_EX

SCardUIDlgSelectCard