PFN_WSK_RECEIVE_FROM funzione di callback (wsk.h)
La funzione WskReceiveFrom riceve un datagramma e le informazioni di controllo associate 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 del datagramma da cui ricevere il datagramma.
[in] Buffer
Puntatore a una struttura di WSK_BUF inizializzata che descrive il buffer di dati che riceve il datagramma 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 dal chiamante che riceve l'indirizzo di trasporto remoto da cui ha avuto origine il datagramma ricevuto. Il buffer deve trovarsi nella memoria non di paging. Il buffer deve anche essere sufficientemente grande da contenere il tipo di struttura SOCKADDR specifico che corrisponde alla famiglia di indirizzi specificata dall'applicazione WSK al momento della creazione del socket del datagram. Questo puntatore è facoltativo e può essere NULL.
[in, out] ControlLength
Puntatore a un 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 sul controllo associate al datagramma ricevuto. Se il valore restituito è zero, non sono presenti informazioni sul controllo per il datagramma. 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 sul controllo associate al datagramma ricevuto. I dati delle informazioni sul controllo associati a un datagramma 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 datagramma 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 datagramma è stato ricevuto come trasmissione a livello di collegamento o con un indirizzo di trasporto di destinazione che è un indirizzo di trasmissione.
MSG_MCAST
Il datagramma è stato ricevuto con un indirizzo di trasporto di destinazione che è un indirizzo multicast.
MSG_TRUNC
Il datagramma è stato troncato perché le dimensioni del datagramma sono maggiori delle dimensioni del buffer specificato dal parametro buffer.
MSG_CTRUNC
I dati delle informazioni sul controllo sono stati troncati perché il numero di byte di informazioni sul controllo è maggiore delle dimensioni del buffer specificato dal parametro ControlInfo.
Questo parametro è facoltativo e può essere NULL.
[in, out] Irp
Puntatore a un IRP allocato dal chiamante usato dal sottosistema WSK per completare l'operazione di ricezione in modo asincrono. Per altre informazioni sull'uso di runtime di integrazione con funzioni WSK, vedere Uso di runtime di integrazione 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 contiene il numero di byte ricevuti. |
|
Il sottosistema WSK non è riuscito a ricevere immediatamente il datagramma dal socket. Il sottosistema WSK completerà l'IRP dopo aver ricevuto il datagrammi 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 di IRP conterrà il numero di byte ricevuti.If the operation succeeds, the IoStatus.Information field of the IRP will contain the number of bytes that were received. |
|
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. |
Osservazioni
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 datagrammi, vedere SIO_WSK_SET_REMOTE_ADDRESS.
Se la WskReceiveFromEvent di un'applicazione WskReceiveFromEvent funzione di callback di eventi è abilitata in un socket di datagrammi e l'applicazione ha anche una chiamata in sospeso alla funzione WskReceiveFrom sullo stesso socket di datagram, quando arrivano i datagrammi, la chiamata in sospeso alla funzione di callback dell'evento WskReceiveFrom avrà la precedenza sull'WskReceiveFromEvent. Il sottosistema WSK chiama il WskReceiveFromEvent funzione di callback degli eventi solo se non sono presenti irP in coda dalle chiamate in sospeso alla funzione WskReceiveFrom. Tuttavia, un'applicazione WSK non deve presupporre che il sottosistema WSK non chiamerà il WskReceiveFromEvent funzione di callback degli eventi per un socket di datagram che ha una chiamata in sospeso alla funzione WskReceiveFrom. Esistono race condition in cui il sottosistema WSK potrebbe comunque chiamare la funzione di callback dell'evento WSK WskReceiveFromE vent per il socket. L'unico modo per un'applicazione WSK per garantire che il sottosistema WSK non chiami la funzione di callback dell'evento WskReceiveFromE vent in un socket di datagrammi non chiamerà la funzione di callback dell'evento WskReceiveFromEvent dell'applicazione funzione di callback dell'evento sul socket.
Se la funzione WskReceiveFrom restituisce STATUS_PENDING, la catena MDL descritta nella struttura WSK_BUF a cui punta il parametro buffer deve rimanere bloccato fino al completamento dell'IRP. Inoltre, la variabile a cui punta il parametro ControlInfoLength, il buffer a cui punta il parametro ControlInfo e la variabile a cui punta il parametro ControlFlags deve rimanere valida 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 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.
Fabbisogno
| 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 |