Estrutura OPENCARDNAMEA (winscard.h)

A estrutura OPENCARDNAME contém as informações que a função GetOpenCardName usa para inicializar um cartão inteligente caixa de diálogo Selecionar Cartão. Chamar SCardUIDlgSelectCard com OPENCARDNAME_EX é recomendável para chamar GetOpenCardName com OPENCARDNAME. OPENCARDNAME é fornecido para compatibilidade com versões anteriores.

Sintaxe

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;

Membros

dwStructSize

Especifica o comprimento, em bytes, da estrutura. Esse membro não deve ser NULL.

hwndOwner

A janela que possui a caixa de diálogo. Esse membro pode ser qualquer identificador de janela válido ou pode ser NULL para o padrão da área de trabalho.

hSCardContext

O contexto usado para comunicação com odo gerenciador de recursos dode cartão inteligente . Chame SCardEstablishContext para definir o de contexto do gerenciador de recursos e SCardReleaseContext para liberá-lo. Esse membro 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.

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

rgguidInterfaces

Reservado para uso futuro. Definir como NULL. Uma matriz de GUIDs que identificam as interfaces necessárias.

cguidInterfaces

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

lpstrRdr

Se o cartão estiver localizado, o buffer lpstrRdr conterá o nome do leitor que contém o cartão localizado. O buffer deve ter pelo menos 256 caracteres.

nMaxRdr

O tamanho, em bytes (versão ANSI) ou caracteres (versãoUnicode), do buffer apontado por lpstrRdr. Se o buffer for muito pequeno para conter as informações do leitor, GetOpenCardName retornará SCARD_E_NO_MEMORY e o tamanho necessário do buffer apontado por lpstrRdr.

lpstrCard

Se o cartão estiver localizado, o buffer de lpstrCard conterá o nome do cartão localizado. O buffer deve ter pelo menos 256 caracteres.

nMaxCard

O tamanho, em bytes (versão ANSI) ou caracteres (versão Unicode), do buffer apontado por lpstrCard. Se o buffer for muito pequeno para conter as informações do cartão, GetOpenCardName retornará SCARD_E_NO_MEMORY e o tamanho necessário do buffer em nMaxCard.

lpstrTitle

Um ponteiro para uma cadeia de caracteres a ser colocada na barra de título da caixa de diálogo. Se esse membro for NULL, o sistema usará o título padrão "Selecionar Cartão:".

dwFlags

Um conjunto de sinalizadores de bits que você pode usar para inicializar a caixa de diálogo. Quando a caixa de diálogo é retornada, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser uma combinação dos sinalizadores a seguir.

Valor	Significado
SC_DLG_MINIMAL_UI	Exibe a caixa de diálogo somente se o cartão que está sendo pesquisado pelo aplicativo de chamada não estiver localizado e disponível para uso em um leitor. Isso permite que o cartão seja encontrado, conectado (por meio do mecanismo da caixa de diálogo interna ou das funções de retorno de chamada do usuário) e retornado ao aplicativo de chamada.
SC_DLG_NO_UI	Não force nenhuma exibição do Selecionarinterface do usuário (interface do usuário) do do usuário, independentemente do resultado da pesquisa.
SC_DLG_FORCE_UI	Force a exibição da interface do usuário Selecionar Cartão, independentemente do resultado da pesquisa.

pvUserData

Um ponteiro nulo para os 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, em seguida, uma chamada interna é feita para SCardConnect que usa dwShareMode e dwPreferredProtocols como os parâmetros dwShareMode e dwPreferredProtocols. Se a conexão for bem-sucedida, hCardHandle será definido como o identificador retornado por hSCardConnect.

Se lpfnConnect for NULL e dwShareMode for zero, a caixa de diálogo retornará hCardHandle como NULL.

dwPreferredProtocols

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

dwActiveProtocol

Retorna o protocolo real em uso quando a caixa de diálogo faz uma conexão com um cartão.

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

lpfnCheck

Um ponteiro para a rotina de verificação de 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, conforme indicado por lpfnDisconnect.

Se o cartão for aceito pela rotina de verificação, VERDADEIRO será retornado. Quando o usuário aceita o cartão, todos os outros cartões conectados no momento serão desconectados, conforme indicado por lpfnDisconnect, e esse cartão será retornado como o cartão localizado. O cartão localizado permanecerá conectado.

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

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

lpfnDisconnect

Um ponteiro para a rotina de desconexão de 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 Ao usar 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.

 

hCardHandle

Um identificador do cartão conectado (por meio de uma caixa de diálogo interna conectar ou um lpfnConnect retorno de chamada).

Observações

Nota

O cabeçalho winscard.h define OPENCARDNAME 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

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard