LPFN_RIORECEIVEEX funzione di callback (mswsock.h)

Articolo
09/23/2023

La funzione RIOReceiveEx riceve i dati di rete su un socket TCP di I/O registrato connesso o un socket UDP di I/O registrato associato con opzioni aggiuntive per l'uso con le estensioni di I/O registrate winsock.

Sintassi

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

Parametri

SocketQueue

Descrittore che identifica un socket UDP di I/O registrato connesso o un socket UDP di I/O registrato associato.

pData

Descrizione della parte del buffer registrato in cui ricevere i dati.

Questo parametro può essere NULL per un socket UDP di I/O registrato associato se l'applicazione non deve ricevere un payload di dati nel datagram UDP.

DataBufferCount

Parametro del conteggio del buffer dei dati che indica se i dati devono essere ricevuti nel buffer a cui punta il parametro pData .

Questo parametro deve essere impostato su zero se pData è NULL. In caso contrario, questo parametro deve essere impostato su 1.

pLocalAddress

Segmento di buffer che al completamento conterrà l'indirizzo locale in cui sono stati ricevuti i dati di rete.

Questo parametro può essere NULL se l'applicazione non vuole ricevere l'indirizzo locale. Se questo parametro non è NULL, il segmento del buffer deve avere almeno le dimensioni di una struttura di SOCKADDR_INET .

pRemoteAddress

Segmento di buffer che al completamento conterrà l'indirizzo remoto da cui sono stati ricevuti i dati di rete.

Questo parametro può essere NULL se l'applicazione non vuole ricevere l'indirizzo remoto. Se questo parametro non è NULL, il segmento del buffer deve avere almeno le dimensioni di una struttura di SOCKADDR_INET .

pControlContext

Una sezione del buffer che al completamento conterrà informazioni aggiuntive sul controllo sull'operazione di ricezione.

Questo parametro può essere NULL se l'applicazione non vuole ricevere le informazioni aggiuntive sul controllo.

pFlags

Flags

Set di flag che modificano il comportamento della funzione RIOReceiveEx .

Il parametro Flags può contenere una combinazione delle opzioni seguenti, definite nel Mswsockdef.h file di intestazione:

RIO_MSG_COMMIT_ONLY

Verrà eseguito il commit delle richieste precedenti aggiunte con RIO_MSG_DEFER flag.

Quando il flag RIO_MSG_COMMIT_ONLY è impostato, non è possibile specificare altri flag. Quando viene impostato il flag RIO_MSG_COMMIT_ONLY , gli argomenti pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags e RequestContext devono essere NULL e l'argomento DataBufferCount deve essere zero.

Questo flag viene in genere usato occasionalmente dopo l'emissione di una serie di richieste con il flag RIO_MSG_DEFER impostato. In questo modo si elimina la necessità di usare il flag di RIO_MSG_DEFER per effettuare l'ultima richiesta senza il flag RIO_MSG_DEFER , causando il completamento dell'ultima richiesta molto più lentamente rispetto ad altre richieste.

A differenza di altre chiamate alla funzione RIOReceiveEx , quando il flag RIO_MSG_COMMIT_ONLY è impostato non è necessario serializzare le chiamate alla funzione RIOReceiveEx . Per una singola RIO_RQ, è possibile chiamare la funzione RIOReceiveEx con RIO_MSG_COMMIT_ONLY in un thread chiamando la funzione RIOReceiveEx in un altro thread.

RIO_MSG_DONT_NOTIFY

La richiesta non deve attivare la funzione RIONotify quando il completamento della richiesta viene inserito nella relativa coda di completamento.

RIO_MSG_DEFER

La richiesta non deve essere eseguita immediatamente. La richiesta verrà inserita nella coda delle richieste, ma potrebbe attivare o meno l'esecuzione della richiesta.

La ricezione dei dati potrebbe essere ritardata fino a quando non viene effettuata una richiesta di ricezione sul RIO_RQ passato nel parametro SocketQueue senza il flag RIO_MSG_DEFER impostato. Per attivare l'esecuzione di tutte le ricevute in una coda di richieste, chiamare la funzione RIOReceive o RIOReceiveEx senza il flag RIO_MSG_DEFER impostato.

Nota

La richiesta di ricezione viene addebitata in base alla capacità di I/O in sospeso nel RIO_RQ passato nel parametro SocketQueue indipendentemente dal fatto che RIO_MSG_DEFER sia impostato.

RIO_MSG_WAITALL

La funzione RIOReceiveEx non verrà completata fino a quando non si verifica uno degli eventi seguenti:

La sezione del buffer fornita dal chiamante nel parametro pData è completamente piena.
La connessione è stata chiusa.
La richiesta è stata annullata o si è verificato un errore.

Questo flag non è supportato nei socket di datagrammi o nei socket senza connessione orientati ai messaggi.

RequestContext

Contesto della richiesta da associare a questa operazione di ricezione.

Valore restituito

Se non si verifica alcun errore, la funzione RIOReceiveEx restituisce TRUE. In questo caso, l'operazione di ricezione viene avviata correttamente e il completamento sarà già stato accodato o l'operazione è stata avviata correttamente e il completamento verrà accodato in un secondo momento.

Un valore FALSE indica che la funzione non è riuscita, l'operazione non è stata avviata correttamente e non verrà accodata alcuna indicazione di completamento. È possibile recuperare un codice di errore specifico chiamando la funzione WSAGetLastError .

Codice restituito	Descrizione
WSAEFAULT	Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. Questo errore viene restituito se un identificatore del buffer viene deregisterato o se un buffer viene liberato per una delle strutture RIO_BUF passate nei parametri prima che l'operazione venga accodata o richiamata.
WSAEINVAL	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se il parametro SocketQueue non è valido, il parametro dwFlags contiene un valore non valido per un'operazione di ricezione o l'integrità della coda di completamento è stata compromessa. Questo errore può essere restituito anche per altri problemi relativi ai parametri.
WSAENOBUFS	Impossibile allocare memoria sufficiente. Questo errore viene restituito se la coda di completamento di I/O associata al parametro SocketQueue è piena o se la coda di completamento di I/O è stata creata con zero voci di ricezione.
WSA_OPERATION_ABORTED	L'operazione è stata annullata mentre l'operazione di ricezione era in sospeso. Questo errore viene restituito se il socket viene chiuso in locale o in remoto o se viene eseguito il comando SIO_FLUSH in WSAIoctl .

Commenti

Un'applicazione può usare la funzione RIOReceiveEx per ricevere i dati di rete in qualsiasi buffer completamente contenuto all'interno di un singolo buffer registrato. I membri Offset e Length della struttura RIO_BUF a cui punta il parametro pData determinano dove vengono ricevuti i dati di rete nel buffer.

Dopo aver chiamato la funzione RIOReceiveEx , il buffer passato nel parametro pData , incluso il RIO_BUFFERID nel membro BufferId della struttura RIO_BUF deve rimanere valido per la durata dell'operazione di ricezione.

Per evitare race condition, un buffer associato a una richiesta di ricezione non deve essere letto o scritto prima del completamento della richiesta. Ciò include l'uso del buffer come origine per una richiesta di invio o la destinazione per un'altra richiesta di ricezione. Le parti di un buffer registrato non associate a alcuna richiesta di ricezione non sono incluse in questa restrizione.

Il parametro pLocalAddress può essere usato per recuperare l'indirizzo locale in cui sono stati ricevuti i dati. Il parametro pRemoteAddress può essere usato per recuperare l'indirizzo remoto da cui sono stati ricevuti i dati. Gli indirizzi locali e remoti vengono restituiti come strutture SOCKADDR_INET . Di conseguenza, il membro Length del RIO_BUF a cui puntano i parametri pLocalAddress o pRemoteAddress deve essere uguale o maggiore della dimensione di una struttura SOCKADDR_INET .

La tabella seguente riepiloga i vari usi dei dati di controllo disponibili per l'uso con le informazioni sul controllo nel membro pControlContext .

Protocollo	cmsg_level	cmsg_type	Descrizione
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Riceve l'interfaccia di arrivo IPv4 originale in cui è stato ricevuto il pacchetto per i socket di datagrammi. Questi dati di controllo vengono usati dai firewall quando viene usato un tunnel Teredo, 6to4 o ISATAP per l'attraversamento NAT IPv4. Il membro cmsg_data[] è un ULONG che contiene il IF_INDEX definito nel file di intestazione ifdef.h . Per altre informazioni, vedere opzioni socket IPPROTO_IP per l'opzione socket IP_ORIGINAL_ARRIVAL_IF.
IPv4	IPPROTO_IP	IP_PKTINFO	Specifica/riceve informazioni sui pacchetti. Per altre informazioni, vedere opzioni socket IPPROTO_IP per l'opzione socket IP_PKTINFO.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Specifica/riceve le opzioni di destinazione.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Specifica/riceve il limite di hop. Per altre informazioni, vedere opzioni socket IPPROTO_IPV6 per l'opzione socket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Specifica/riceve opzioni hop-by-hop.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Specifica l'indirizzo hop successivo.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Specifica/riceve le informazioni sui pacchetti. Per altre informazioni, vedere l'opzione IPPROTO_IPV6 Socket Options for the IPV6_PKTINFO socket .For more information, see the IPPROTO_IPV6 Socket Options for the IPV6_PKTINFO socket option.
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Specifica/riceve l'intestazione di routing.

I dati di controllo sono costituiti da uno o più oggetti dati di controllo, ognuno a partire da una struttura WSACMSMSGHDR , definita come segue:

} WSACMSGHDR;

I membri della struttura WSACMSGHDR sono i seguenti:

Termine	Descrizione
cmsg_len	Numero di byte di dati a partire dall'inizio di WSACMSGHDR alla fine dei dati (esclusi i byte di riempimento che potrebbero seguire i dati).
cmsg_level	Protocollo che ha originato le informazioni sul controllo.
cmsg_type	Tipo specifico del protocollo delle informazioni sul controllo.

Il parametro Flags può essere usato per influenzare il comportamento della chiamata alla funzione RIOReceiveEx oltre le opzioni specificate per il socket associato. Il comportamento di questa funzione è determinato da una combinazione di qualsiasi opzione socket impostata sul socket associato al parametro SocketQueue e ai valori specificati nel parametro Flags .

Nota

Il puntatore alla funzione RIOReceiveEx deve essere ottenuto in fase di esecuzione eseguendo una chiamata alla funzione WSAIoctl con il codice opcode SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER specificato. Il buffer di input passato alla funzione WSAIoctl deve contenere WSAID_MULTIPLE_RIO, un identificatore univoco globale (GUID) il cui valore identifica le funzioni di estensione I/O registrate Winsock. In caso di esito positivo, l'output restituito dalla funzione WSAIoctl contiene un puntatore alla struttura RIO_EXTENSION_FUNCTION_TABLE che contiene puntatori alle funzioni di estensione di I/O registrate Winsock. Il SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL è definito nel file di intestazione Ws2def.h . Il GUID WSAID_MULTIPLE_RIO è definito nel file di intestazione Mswsock.h .

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Intestazione	mswsock.h

Condividi tramite