Funzione WSAAsyncGetServByName (winsock.h)

La funzione WSAAsyncGetServByName recupera in modo asincrono le informazioni sul servizio che corrispondono a un nome e a una porta del servizio.

Sintassi

HANDLE WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

Parametri

[in] hWnd

Handle della finestra che deve ricevere un messaggio al termine della richiesta asincrona.

[in] wMsg

Messaggio da ricevere al termine della richiesta asincrona.

[in] name

Puntatore a un nome di servizio con terminazione Null.

[in] proto

Puntatore a un nome di protocollo. Può essere NULL, nel qual caso WSAAsyncGetServByName cercherà la prima voce del servizio per cui s_name o una delle s_aliases corrisponde al nome specificato. In caso contrario, WSAAsyncGetServByName corrisponde sia al nome che al proto.

[out] buf

Puntatore all'area dati per ricevere i dati servent . L'area dati deve essere maggiore delle dimensioni di una struttura servent perché l'area dati viene usata da Windows Sockets per contenere una struttura servent e tutti i dati a cui fanno riferimento i membri della struttura servent . È consigliabile usare un buffer di byte MAXGETHOSTSTRUCT.

[in] buflen

Dimensioni dell'area dati per il parametro buf , in byte.

Valore restituito

Il valore restituito specifica se l'operazione asincrona è stata avviata correttamente. Non implica l'esito positivo o negativo dell'operazione stessa.

Se non si verifica alcun errore, WSAAsyncGetServByName restituisce un valore diverso da zero di tipo HANDLE che rappresenta l'handle di attività asincrona per la richiesta (da non confondere con un HTASK di Windows). Questo valore può essere usato in due modi. Può essere usato per annullare l'operazione usando WSACancelAsyncRequest oppure per trovare una corrispondenza con operazioni asincrone e messaggi di completamento, esaminando il parametro del messaggio wParam .

Se non è stato possibile avviare l'operazione asincrona, WSAAsyncServByName restituisce un valore zero e un numero di errore specifico può essere recuperato chiamando WSAGetLastError.

Quando una finestra dell'applicazione riceve un messaggio, è possibile impostare i codici di errore seguenti. Come descritto in precedenza, possono essere estratti dal parametro lParam nel messaggio di risposta usando la macro WSAGETASYNCERROR .

Al momento della chiamata di funzione possono verificarsi gli errori seguenti e indicare che non è stato possibile avviare l'operazione asincrona.

Commenti

La funzione WSAAsyncGetServByName è una versione asincrona di getservbyname e viene usata per recuperare le informazioni sul servizio corrispondenti a un nome di servizio. Windows Sockets avvia l'operazione e torna immediatamente al chiamante, passando un handle di attività opaco e asincrono che l'applicazione può usare per identificare l'operazione. Al termine dell'operazione, i risultati (se presenti) vengono copiati nel buffer fornito dal chiamante e viene inviato un messaggio alla finestra dell'applicazione.

Al termine dell'operazione asincrona, la finestra dell'applicazione indicata dal parametro hWnd riceve il messaggio nel parametro wMsg . Il parametro wParam contiene l'handle di attività asincrono restituito dalla chiamata di funzione originale. Gli alti 16 bit di lParam contengono qualsiasi codice di errore. Il codice di errore può essere qualsiasi errore definito in Winsock2.h. Un codice di errore pari a zero indica il completamento dell'operazione asincrona.

Al completamento, il buffer specificato nella chiamata di funzione originale contiene una struttura servent . Per accedere ai membri di questa struttura, è necessario eseguire il cast dell'indirizzo del buffer originale a un puntatore alla struttura servent e accedere in base alle esigenze.

Se il codice di errore è WSAENOBUFS, la dimensione del buffer specificato da buflen nella chiamata originale era troppo piccola per contenere tutte le informazioni risultanti. In questo caso, i 16 bit bassi di lParam contengono le dimensioni del buffer necessarie per fornire tutte le informazioni necessarie. Se l'applicazione decide che i dati parziali non sono adeguati, può eseguire nuovamente la chiamata di funzione WSAAsyncGetServByName con un buffer sufficientemente grande da ricevere tutte le informazioni desiderate, ovvero non inferiori ai 16 bit bassi di lParam.

Il buffer specificato per questa funzione viene usato da Windows Sockets per costruire una struttura servent insieme al contenuto delle aree dati a cui fanno riferimento i membri della stessa struttura servent . Per evitare l'errore WSAENOBUFS , l'applicazione deve fornire un buffer di almeno MAXGETHOSTSTRUCT byte (come definito in Winsock2.h).

Il codice di errore e la lunghezza del buffer devono essere estratti da lParam usando le macro WSAGETASYNCERROR e WSAGETASYNCBUFLEN, definite in Winsock2.h come:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

L'uso di queste macro consente di ottimizzare la portabilità del codice sorgente per l'applicazione.

Requisiti

Vedi anche

WSACancelAsyncRequest

Funzioni Winsock

Informazioni di riferimento su Winsock

getservbyname