estrutura OPENCARD_SEARCH_CRITERIAA (winscard.h)

  • Artigo

A estrutura OPENCARD_SEARCH_CRITERIA é usada pela função SCardUIDlgSelectCard para reconhecer cartões que atendem aos requisitos estabelecidos pelo chamador. No entanto, você pode chamar SCardUIDlgSelectCard sem usar essa estrutura.

Sintaxe

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;

Membros

dwStructSize

O comprimento, em bytes, da estrutura. Não deve ser NULL.

lpstrGroupNames

Um ponteiro para um buffer que contém cadeias de caracteres de nome de grupo terminadas em nulo. A última cadeia de caracteres no buffer deve ser encerrada por dois caracteres nulos. Cada cadeia de caracteres é o nome de um grupo de cartões que deve ser incluído na pesquisa. Se lpstrGroupNames for NULL, o grupo padrão (Scard$DefaultReaders) será pesquisado.

nMaxGroupNames

O número máximo de bytes (versão ANSI) ou caracteres (versão Unicode ) na cadeia de caracteres lpstrGroupNames .

rgguidInterfaces

Reservado para uso futuro. Uma matriz de GUIDs que identifica as interfaces necessárias. Defina esse membro como NULL.

cguidInterfaces

Reservado para uso futuro. O número de interfaces na matriz rgguidInterfaces . Defina esse membro como NULL.

lpstrCardNames

Um ponteiro para um buffer que contém cadeias de caracteres de nome de cartão terminadas em nulo. A última cadeia de caracteres no buffer deve ser encerrada por dois caracteres nulos. Cada cadeia de caracteres é o nome de um cartão que deve ser localizado.

nMaxCardNames

O número máximo de bytes (versão ANSI) ou caracteres (versão Unicode) na cadeia de caracteres lpstrGroupNames .

lpfnCheck

Um ponteiro para a rotina de verificação cartão do chamador. Se nenhuma verificação de cartão especial for necessária, esse ponteiro será NULL. Se o cartão for rejeitado pela rotina de verificação, FALSE será retornado e o cartão será desconectado. Se o cartão for aceito pela rotina de verificação, TRUE será retornado.

O protótipo da rotina de marcar é o seguinte.

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

Um ponteiro para a rotina de conexão cartão do chamador. Se o chamador precisar executar processamento adicional para se conectar ao cartão, esse ponteiro de função será definido como a função de conexão do usuário. Se a função de conexão for bem-sucedida, o cartão será deixado conectado e inicializado e o identificador cartão será retornado.

O protótipo da rotina de conexão é o seguinte.

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

Um ponteiro para a rotina de desconexão cartão do chamador.

O protótipo para a rotina de desconexão é o seguinte.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);
Nota Quando você usa lpfnConnect, lpfnCheck e lpfnDisconnect, todos os três procedimentos de retorno de chamada devem estar presentes. O uso desses retornos de chamada permite uma verificação adicional de que o aplicativo de chamada encontrou o cartão apropriado. Essa é a melhor maneira de garantir que o cartão apropriado esteja selecionado. No entanto, ao usar um valor que não seja NULL para lpfnCheck, lpfnConnect e lpfnDisconnect não devem ser NULL (e pvUserData também deve ser fornecido), ou dwShareMode e dwPreferredProtocols devem ser definidos .
 

pvUserData

Ponteiro nulo para dados do usuário. Esse ponteiro é passado de volta para o chamador nas rotinas Conectar, Verificar e Desconectar.

dwShareMode

Se lpfnConnect não for NULL, os membros dwShareMode e dwPreferredProtocols serão ignorados . Se lpfnConnect for NULL e dwShareMode não for zero, uma chamada interna será feita para SCardConnect que usa dwShareMode e dwPreferredProtocols como o parâmetro .

dwPreferredProtocols

Usado para conexão interna, conforme descrito em dwShareMode.

Comentários

Observação

O cabeçalho winscard.h define OPENCARD_SEARCH_CRITERIA como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Cabeçalho winscard.h

Confira também

OPENCARDNAME_EX

SCardUIDlgSelectCard