PFN_WSK_RECEIVE_FROM funzione di callback (wsk.h)
La funzione WskReceiveFrom riceve un datagram e qualsiasi informazione di controllo associata da un indirizzo di trasporto remoto.
Sintassi
PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;
NTSTATUS PfnWskReceiveFrom(
[in] PWSK_SOCKET Socket,
[in] PWSK_BUF Buffer,
ULONG Flags,
[out, optional] PSOCKADDR RemoteAddress,
[in, out] PULONG ControlLength,
[out, optional] PCMSGHDR ControlInfo,
[out, optional] PULONG ControlFlags,
[in, out] PIRP Irp
)
{...}
Parametri
[in] Socket
Puntatore a una struttura WSK_SOCKET che specifica l'oggetto socket per il socket datagram da cui ricevere il datagram.
[in] Buffer
Puntatore a una struttura di WSK_BUF inizializzata che descrive il buffer di dati che riceve il datagram dal socket.
Flags
Questo parametro è riservato per l'uso del sistema. Un'applicazione WSK deve impostare questo parametro su zero.
[out, optional] RemoteAddress
Puntatore a un buffer allocato del chiamante che riceve l'indirizzo di trasporto remoto da cui ha avuto origine il datagram ricevuto. Il buffer deve trovarsi nella memoria non a pagina. Il buffer deve anche essere abbastanza grande per contenere il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK quando ha creato il socket del datagram. Questo puntatore è facoltativo e può essere NULL.
[in, out] ControlLength
Puntatore a un oggetto ULONG che specifica le dimensioni del buffer a cui punta il parametro ControlInfo . Al termine dell'operazione di ricezione, la variabile riceve le dimensioni delle informazioni di controllo associate al datagrammo ricevuto. Se il valore restituito è zero, non sono presenti informazioni di controllo per il datagram. Questo puntatore è facoltativo e può essere NULL. Se questo parametro è NULL, il parametro ControlInfo viene ignorato.
[out, optional] ControlInfo
Puntatore a un buffer allocato dal chiamante che riceve le informazioni di controllo associate al datagrammo ricevuto. I dati delle informazioni di controllo associati a un datagram sono costituiti da uno o più oggetti dati di controllo, ognuno dei quali inizia con una struttura CMSGHDR . Se non sono presenti informazioni di controllo per il datagram ricevuto, il contenuto del buffer non è definito. Questo puntatore è facoltativo e può essere NULL. Se il parametro ControlInfoLength è NULL, il parametro ControlInfo deve essere NULL.
[out, optional] ControlFlags
Puntatore a una variabile tipizzata ULONG che riceve l'OR bit per bit di una combinazione dei flag seguenti:
MSG_BCAST
Il datagram è stato ricevuto come trasmissione a livello di collegamento o con un indirizzo di trasporto di destinazione che è un indirizzo di trasmissione.
MSG_MCAST
Il datagram è stato ricevuto con un indirizzo di trasporto di destinazione che è un indirizzo multicast.
MSG_TRUNC
Il datagram è stato troncato perché le dimensioni del datagram sono maggiori delle dimensioni del buffer specificato dal parametro Buffer .
MSG_CTRUNC
I dati delle informazioni di controllo sono stati troncati perché il numero di byte delle informazioni di controllo è maggiore delle dimensioni del buffer specificato dal parametro ControlInfo .
Questo parametro è facoltativo e può essere NULL.
[in, out] Irp
Puntatore a un'IRP allocata dal chiamante che il sottosistema WSK usa per completare l'operazione di ricezione in modo asincrono. Per altre informazioni sull'uso di IRP con funzioni WSK, vedere Uso di IRP con Funzioni kernel Winsock.
Valore restituito
WskReceiveFrom restituisce uno dei codici NTSTATUS seguenti:
| Codice restituito | Descrizione |
|---|---|
|
I dati sono stati ricevuti correttamente dal socket. L'IRP verrà completato con lo stato di esito positivo. Il campo IoStatus.Information dell'IRP contiene il numero di byte ricevuti. |
|
Il sottosistema WSK non è riuscito a ricevere immediatamente il datagram dal socket. Il sottosistema WSK completerà l'IRP dopo aver ricevuto il datagram dal socket. Lo stato dell'operazione di ricezione verrà restituito nel campo IoStatus.Status dell'IRP . Se l'operazione ha esito positivo, il campo IoStatus.Information dell'IRP conterrà il numero di byte ricevuti. |
|
Il socket non è più funzionale. L'IRP verrà completato con lo stato di errore. L'applicazione WSK deve chiamare la funzione WskCloseSocket per chiudere il socket il prima possibile. |
|
Si è verificato un errore. L'IRP verrà completato con lo stato di errore. |
Commenti
Se l'applicazione WSK ha impostato un indirizzo di trasporto remoto fisso per il socket del datagram, i datagrammi ricevuti da qualsiasi altro indirizzo di trasporto remoto verranno eliminati dal sottosistema WSK. Per altre informazioni sull'impostazione dell'indirizzo di trasporto remoto per un socket di datagram, vedere SIO_WSK_SET_REMOTE_ADDRESS.
Se la funzione di callback dell'evento WskReceiveFromEvent di un'applicazione WskReceiveFrom è abilitata in un socket di datagrammi e l'applicazione ha anche una chiamata in sospeso alla funzione WskReceiveFrom nello stesso socket di datagrammi, quando arrivano i datagrammi, la chiamata in sospeso alla funzione WskReceiveFrom avrà la precedenza sulla funzione di callback dell'evento WskReceiveFromEvent . Il sottosistema WSK chiama la funzione di callback dell'evento WskReceiveFromEvent dell'applicazione solo se non sono presenti gruppi di integrazione accodati da chiamate in sospeso alla funzione WskReceiveFrom . Tuttavia, un'applicazione WSK non presuppone che il sottosistema WSK non chiamerà la funzione WskReceiveFromEvent dell'evento WskReceiveFromEvent per un socket di datagram con una chiamata in sospeso alla funzione WskReceiveFrom . Esistono condizioni di gara in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'applicazione WskReceiveFromEvent per il socket. L'unico modo per un'applicazione WSK per assicurarsi che il sottosistema WSK non chiamerà la funzione di callback dell'evento WskReceiveFromEvent in un socket di datagram è disabilitare la funzione di callback dell'evento WskReceiveFromEvent dell'applicazione nel socket.
Se la funzione WskReceiveFrom restituisce STATUS_PENDING, la catena MDL descritta nella struttura WSK_BUF a cui punta il parametro Buffer deve rimanere bloccata fino al completamento dell'IRP. Inoltre, la variabile a cui fa riferimento il parametro ControlInfoLength , il buffer a cui punta il parametro ControlInfo e la variabile a cui punta il parametro ControlFlags deve rimanere valida anche fino al completamento dell'IRP. Se l'applicazione WSK ha allocato questi buffer o variabili con una delle funzioni ExAllocateXxx , non può liberare la memoria con la funzione ExFreeXxx corrispondente fino al completamento dell'IRP. Se l'applicazione WSK ha allocato questi buffer o variabili nello stack, non può restituire dalla funzione che chiama la funzione WskReceiveFrom fino al completamento dell'IRP.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows. |
| Piattaforma di destinazione | Universale |
| Intestazione | wsk.h (include Wsk.h) |
| IRQL | <= DISPATCH_LEVEL |