Estrutura OPENCARDNAMEA (winscard.h)
A estrutura OPENCARDNAME contém as informações que a função GetOpenCardName usa para inicializar um smart cartão caixa de diálogo Selecionar Cartão. Chamar SCardUIDlgSelectCard com OPENCARDNAME_EX é recomendável ao 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 o gerenciador de recursos de cartão inteligente. Chame SCardEstablishContext para definir o 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. Defina como NULL. Uma matriz de GUIDs que identificam as interfaces necessárias.
cguidInterfaces
Reservado para uso futuro. Defina 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ão Unicode ), 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 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 de 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 retorna, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser uma combinação dos sinalizadores a seguir.
| Valor | Significado |
|---|---|
|
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. |
|
Não force nenhuma exibição da interface do usuário (Interface do usuário) Selecionar Cartão, independentemente do resultado da pesquisa. |
|
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, uma chamada interna será feita para SCardConnect que usa dwShareMode e dwPreferredProtocols como os parâmetrosdwShareMode 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 o cartão rotina de conexã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 para o 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
);
lpfnCheck
Um ponteiro para o cartão verificar a rotina 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, TRUE será retornado. Quando o usuário aceitar 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 marcar é 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 o cartão a rotina de desconexã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
);
hCardHandle
Um identificador do cartão conectado (por meio de uma caixa de diálogo interna conectar ou um retorno de chamada lpfnConnect).
Comentários
Observação
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 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
| 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de