Função WSAQuerySocketSecurity (ws2tcpip.h)

Artigo
08/28/2023

A função WSAQuerySocketSecurity consulta informações sobre a segurança aplicada a uma conexão em um soquete.

Sintaxe

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

Parâmetros

[in] Socket

Um descritor que identifica um soquete para o qual as informações de segurança estão sendo consultadas.

[in, optional] SecurityQueryTemplate

Um ponteiro para uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE que especifica o tipo de informações de consulta a serem retornadas.

Uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE apontada por esse parâmetro pode conter zeros para todos os membros solicitarem informações de segurança padrão. No retorno bem-sucedido, somente o membro Flags no SOCKET_SECURITY_QUERY_INFO será definido no parâmetro SecurityQueryInfo retornado.

Esse parâmetro poderá ser um ponteiro NULL se o parâmetro Socket tiver sido criado com um protocolo de IPPROTO_TCP. Nesse caso, as informações retornadas são as mesmas que se uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE com todos os valores definidos como zero fosse passada. Esse parâmetro deve ser especificado para um soquete com protocolo de IPPROTO_TCP se mais do que as informações de segurança padrão forem necessárias.

Se a estrutura SOCKET_SECURITY_QUERY_TEMPLATE for especificada com o membro PeerTokenAccessMask não especificado (definido como zero), a função WSAQuerySocketSecurity não retornará os membros PeerApplicationAccessTokenHandle e PeerMachineAccessTokenHandle na estrutura SOCKET_SECURITY_QUERY_INFO .

Se um parâmetro Socket tiver sido criado com um protocolo diferente de IPPROTO_TCP, o parâmetro SecurityQueryTemplate deverá ser especificado. Nesses casos, o membro PeerAddress da estrutura SOCKET_SECURITY_QUERY_TEMPLATE deve especificar uma família de endereços de AF_INET ou AF_INET6 juntamente com o endereço IP do par e o número da porta.

[in] SecurityQueryTemplateLen

O tamanho, em bytes, do parâmetro SecurityQueryTemplate .

Esse parâmetro poderá ser zero se o parâmetro Socket tiver sido criado com um protocolo de IPPROTO_TCP. Caso contrário, esse parâmetro deve ser do tamanho de uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Um ponteiro para um buffer que receberá uma estrutura SOCKET_SECURITY_QUERY_INFO que contém as informações consultadas. Esse valor pode ser definido como NULL para consultar o tamanho do buffer de saída.

[in, out] SecurityQueryInfoLen

Na entrada, um ponteiro para o tamanho, em bytes, do parâmetro SecurityQueryInfo . Se o buffer for muito pequeno para receber as informações consultadas, a chamada retornará SOCKET_ERROR e o número de bytes necessários para retornar as informações consultadas será definido no valor apontado por esse parâmetro. Em uma chamada bem-sucedida, o número de bytes copiados é retornado.

[in, optional] Overlapped

Um ponteiro para uma estrutura WSAOVERLAPPED . Esse parâmetro é ignorado para soquetes não sobrepostos.

[in, optional] CompletionRoutine

Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída. Esse parâmetro é ignorado para soquetes não sobrepostos.

Retornar valor

Se a função obtiver êxito, o valor retornado será zero. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá ser recuperado chamando WSAGetLastError.

Alguns códigos de erro possíveis estão listados abaixo.

Código do erro	Significado
WSAEAFNOSUPPORT	A família de endereços especificada não tem suporte.
WSAECONNRESET	Para um soquete de fluxo, o circuito virtual foi redefinido pelo lado remoto. O aplicativo deve fechar o soquete porque ele não pode ser mais usado. Para um soquete de datagrama UDP, esse erro indicaria que uma operação de envio anterior resultou em uma mensagem "Porta Inacessível" ICMP.
WSAEFAULT	O sistema detectou um endereço de ponteiro inválido ao tentar usar um parâmetro. Esse erro será retornado se o parâmetro SecurityQueryInfoLen for um ponteiro NULL .
WSAEINVAL	Um parâmetro inválido foi passado. Esse erro será retornado se o soquete passado no parâmetro Socket não tiver sido criado com uma família de endereços do AF_INET ou AF_INET6 e um tipo de soquete de SOCK_DGRAM ou SOCK_STREAM.
WSAEMSGSIZE	Um buffer passado era muito pequeno. Esse erro é retornado para um parâmetro Socket quando o protocolo não foi IPPROTO_TCP se o parâmetro SecurityQueryInfo for um ponteiro NULL ou o parâmetro SecurityQueryTemplateLen for menor que o tamanho de uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	O descritor passado no parâmetro Socket não é um soquete válido.

Comentários

A função WSAQuerySocketSecurity fornece um método para consultar as configurações de segurança atuais em um soquete. Depois que uma conexão é estabelecida, a função WSAQuerySocketSecurity permite que um aplicativo consulte as propriedades de segurança da conexão, o que pode incluir informações sobre tokens de acesso par.

Para soquetes orientados à conexão, é preferível chamar a função WSAQuerySocketSecurity imediatamente após a conexão ser estabelecida. Para soquetes sem conexão, é preferível chamar a função WSAQuerySocketSecurity imediatamente após os dados serem enviados para um novo endereço par ou recebidos de um novo endereço par. A função WSAQuerySocketSecurity pode ser chamada várias vezes em um único soquete.

Essa função simplifica a necessidade de chamar a função WSAIoctl com um parâmetro dwIoControlCode definido como SIO_QUERY_SECURITY.

A função WSAQuerySocketSecurity pode ser chamada em um parâmetro Socket criado com uma família de endereços de AF_INET ou AF_INET6.

Se o parâmetro Socket tiver sido criado com um protocolo de IPPROTO_TCP, o parâmetro SecurityQueryTemplate poderá ser NULL e o parâmetro SecurityQueryTemplateLen poderá ser zero. Caso contrário, o parâmetro SecurityQueryTemplate deverá apontar para uma estrutura SOCKET_SECURITY_QUERY_TEMPLATE .

Para um aplicativo cliente que usa soquetes orientados à conexão (soquete criado com um protocolo de IPPROTO_TCP), a função WSAQuerySocketSecurity deve ser chamada após o retorno da função connect, ConnectEx ou WSAConnect. Para um aplicativo de servidor que usa soquetes orientados à conexão (protocolo de IPPROTO_TCP), a função WSAQuerySocketSecurity deve ser chamada após o retorno da função accept, AcceptEx ou WSAAccept .

Para soquetes sem conexão (soquete criado com um protocolo de IPPROTO_UDP), o aplicativo deve chamar a função WSAQuerySocketSecurity imediatamente após a chamada WSASendTo ou WSARecvFrom retornar para um novo endereço par.

Um erro será retornado se as condições a seguir não forem atendidas.

A família de endereços do parâmetro Socket deve ser AF_INET ou AF_INET6.
O tipo de soquete deve ser SOCK_STREAM ou SOCK_DGRAM.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ws2tcpip.h
Biblioteca	Fwpuclnt.lib
DLL	Fwpuclnt.dll