PFN_WSK_RECEIVE_FROM funzione di callback (wsk.h)

Articolo
02/27/2024

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
STATUS_SUCCESS	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.
STATUS_PENDING	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.
STATUS_FILE_FORCED_CLOSED	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.
Altri codici di stato	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