Funzione WSAQuerySocketSecurity (ws2tcpip.h)

Articolo
03/04/2024

La funzione WSAQuerySocketSecurity esegue query sulle informazioni sulla sicurezza applicata a una connessione in un socket.

Sintassi

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

Parametri

[in] Socket

Descrittore che identifica un socket per cui vengono eseguite query informazioni sulla sicurezza.

[in, optional] SecurityQueryTemplate

Puntatore a una struttura SOCKET_SECURITY_QUERY_TEMPLATE che specifica il tipo di informazioni di query da restituire.

Una struttura SOCKET_SECURITY_QUERY_TEMPLATE puntata da questo parametro può contenere zero per tutti i membri per richiedere informazioni di sicurezza predefinite. In caso di esito positivo, nel parametro SecurityQueryInfo restituito verrà impostato solo il membro Flag nel SOCKET_SECURITY_QUERY_INFO.

Questo parametro può essere un puntatore NULL se il parametro Socket è stato creato con un protocollo di IPPROTO_TCP. In questo caso, le informazioni restituite sono uguali a se è stata passata una struttura SOCKET_SECURITY_QUERY_TEMPLATE con tutti i valori impostati su zero. Questo parametro deve essere specificato per un socket con protocollo di IPPROTO_TCP se sono necessarie più informazioni di sicurezza predefinite.

Se la struttura SOCKET_SECURITY_QUERY_TEMPLATE viene specificata con il membro PeerTokenAccessMask non specificato (impostato su zero), la funzione WSAQuerySocketSecurity non restituirà i membri PeerApplicationAccessTokenHandle e PeerMachineAccessTokenHandle nella struttura SOCKET_SECURITY_QUERY_INFO .

Se un parametro Socket è stato creato con un protocollo non uguale a IPPROTO_TCP, è necessario specificare il parametro SecurityQueryTemplate . In questi casi, il membro PeerAddress della struttura SOCKET_SECURITY_QUERY_TEMPLATE deve specificare una famiglia di indirizzi di AF_INET o AF_INET6 insieme all'indirizzo IP peer e al numero di porta.

[in] SecurityQueryTemplateLen

Dimensioni, in byte, del parametro SecurityQueryTemplate .

Questo parametro può essere zero se il parametro Socket è stato creato con un protocollo di IPPROTO_TCP. In caso contrario, questo parametro deve essere la dimensione di una struttura SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Puntatore a un buffer che riceverà una struttura SOCKET_SECURITY_QUERY_INFO contenente le informazioni sottoposte a query. Questo valore può essere impostato su NULL per eseguire query sulle dimensioni del buffer di output.

[in, out] SecurityQueryInfoLen

In input, un puntatore alle dimensioni, in byte, del parametro SecurityQueryInfo . Se il buffer è troppo piccolo per ricevere le informazioni di query, la chiamata restituirà SOCKET_ERROR e il numero di byte necessari per restituire le informazioni query verrà impostato nel valore a cui punta questo parametro. In una chiamata riuscita viene restituito il numero di byte copiati.

[in, optional] Overlapped

Puntatore a una struttura WSAOVERLAPPED . Questo parametro viene ignorato per socket non sovrapposti.

[in, optional] CompletionRoutine

Puntatore alla routine di completamento chiamata al termine dell'operazione. Questo parametro viene ignorato per socket non sovrapposti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Di seguito sono elencati alcuni codici di errore possibili.

Codice di errore	Significato
WSAEAFNOSUPPORT	La famiglia di indirizzi specificata non è supportata.
WSAECONNRESET	Per un socket di flusso, il circuito virtuale è stato reimpostato dal lato remoto. L'applicazione deve chiudere il socket che non è più utilizzabile. Per un socket di datagrammi UDP, questo errore indica che un'operazione di invio precedente ha generato un messaggio ICMP "Port Unreachable".
WSAEFAULT	Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un parametro. Questo errore viene restituito se il parametro SecurityQueryInfoLen era un puntatore NULL .
WSAEINVAL	È stato passato un parametro non valido. Questo errore viene restituito se il socket passato nel parametro Socket non è stato creato con una famiglia di indirizzi del AF_INETo AF_INET6 e un tipo di socket di SOCK_DGRAM o SOCK_STREAM.
WSAEMSGSIZE	Un buffer passato era troppo piccolo. Questo errore viene restituito per un parametro Socket quando il protocollo non è IPPROTO_TCP se il parametro SecurityQueryInfo è un puntatore NULL o il parametro SecurityQueryTemplateLen è minore delle dimensioni di una struttura di SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	Il descrittore passato nel parametro Socket non è un socket valido.

Commenti

La funzione WSAQuerySocketSecurity fornisce un metodo per eseguire query sulle impostazioni di sicurezza correnti in un socket. Dopo aver stabilito una connessione, la funzione WSAQuerySocketSecurity consente a un'applicazione di eseguire query sulle proprietà di sicurezza della connessione, che possono includere informazioni sui token di accesso peer.

Per i socket orientati alla connessione, è preferibile chiamare la funzione WSAQuerySocketSecurity immediatamente dopo la creazione di una connessione. Per i socket senza connessione, è preferibile chiamare la funzione WSAQuerySocketSecurity immediatamente dopo l'invio dei dati a un nuovo indirizzo peer o ricevuto da un nuovo indirizzo peer. La funzione WSAQuerySocketSecurity può essere chiamata più volte in un singolo socket.

Questa funzione semplifica la chiamare la funzione WSAIoctl con un parametro dwIoControlCode impostato su SIO_QUERY_SECURITY.

La funzione WSAQuerySocketSecurity può essere chiamata su un parametro Socket creato con una famiglia di indirizzi di AF_INET o AF_INET6.

Se il parametro Socket è stato creato con un protocollo di IPPROTO_TCP, il parametro SecurityQueryTemplate può essere NULL e il parametro SecurityQueryTemplateLen può essere zero. In caso contrario, il parametro SecurityQueryTemplate deve puntare a una struttura SOCKET_SECURITY_QUERY_TEMPLATE .

Per un'applicazione client che usa socket orientati alla connessione (socket creato con un protocollo di IPPROTO_TCP), la funzioneWSAQuerySocketSecurity deve essere chiamata dopo la restituzione della funzione connect, ConnectEx o WSAConnect. Per un'applicazione server che usa socket orientati alla connessione (protocollo di IPPROTO_TCP), la funzioneWSAQuerySocketSecurity deve essere chiamata dopo la restituzione della funzione accept, AcceptEx o WSAAccept.

Per i socket senza connessione (socket creato con un protocollo di IPPROTO_UDP), l'applicazione deve chiamare la funzione WSAQuerySocketSecurity immediatamente dopo la chiamata WSASendTo o WSARecvFrom restituisce un nuovo indirizzo peer.

Se le condizioni seguenti non vengono soddisfatte, verrà restituito un errore.

La famiglia di indirizzi del parametro Socket deve essere AF_INET o AF_INET6.
Il tipo di socket deve essere SOCK_STREAM o SOCK_DGRAM.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2tcpip.h
Libreria	Fwpuclnt.lib
DLL	Fwpuclnt.dll