estrutura OPENCARD_SEARCH_CRITERIAW (winscard.h)

Artigo
11/20/2024

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

Sintaxe

typedef struct {
  DWORD          dwStructSize;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAW, *POPENCARD_SEARCH_CRITERIAW, *LPOPENCARD_SEARCH_CRITERIAW;

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) no lpstrGroupNames cadeia de caracteres.

lpfnCheck

Um ponteiro para a rotina de verificação do 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, VERDADEIRO será retornado.

O protótipo da rotina de verificação é 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 de 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 de 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 do cartão do chamador.

O protótipo da 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
);

Observação Quando você usa lpfnConnect, lpfnChecke 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 é NULL para lpfnCheck, lpfnConnect e lpfnDisconnect não devem ser NULL (e pvUserData também devem ser fornecidos) 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.

Observações

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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

Consulte também

OPENCARDNAME_EX

SCardUIDlgSelectCard

Compartilhar via