LPFN_RIORECEIVE funzione di callback (mswsock.h)

La funzione RIOReceive riceve i dati di rete in un socket TCP I/O connesso o un socket UDP di I/O registrato associato per l'uso con le estensioni di I/O registrate Winsock.

Sintassi

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parametri

SocketQueue

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

pData

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

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

DataBufferCount

Parametro conteggio buffer 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.

Flags

Set di flag che modificano il comportamento della funzione RIOReceive .

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

RIO_MSG_COMMIT_ONLY

Le richieste precedenti aggiunte con il flag di RIO_MSG_DEFER verranno eseguite il commit.

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

Questo flag viene normalmente usato occasionalmente dopo l'emissione di una serie di richieste con il set di flag di RIO_MSG_DEFER . Ciò consente di eliminare la necessità di usare il flag RIO_MSG_DEFER per effettuare l'ultima richiesta senza il flag RIO_MSG_DEFER , che causa il completamento dell'ultima richiesta molto più lentamente di altre richieste.

A differenza di altre chiamate alla funzione RIOReceive , quando il flag RIO_MSG_COMMIT_ONLY viene impostato sulle chiamate alla funzione RIOReceive non è necessario serializzare. Per una singola RIO_RQ, la funzione RIOReceive può essere chiamata con RIO_MSG_COMMIT_ONLY su un thread durante la chiamata alla funzione RIOReceive in un altro thread.

RIO_MSG_DONT_NOTIFY

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

RIO_MSG_DEFER

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

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

Nota

La richiesta di ricezione viene addebitata sulla 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 RIOReceive non verrà completata finché non si verifica uno degli eventi seguenti:

• Il segmento di buffer fornito dal chiamante nel parametro pData è completamente pieno.
• La connessione è stata chiusa.
• La richiesta è stata annullata o si è verificato un errore.

Questo flag non è supportato nei socket UDP.

RequestContext

Contesto della richiesta da associare a questa operazione di ricezione.

Valore restituito

Se non si verifica alcun errore, la funzione RIOReceive 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à eseguita 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 di buffer viene deregisterato o viene liberato un buffer per una delle strutture RIO_BUF passate nei parametri prima che l'operazione venga accodata o richiamata.
WSAEINVAL	Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro SocketQueue non è valido, il parametro Flags 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 con i parametri.
WSAENOBUFS	Impossibile allocare memoria sufficiente. Questo errore viene restituito se la coda di completamento di I/O associata al parametro SocketQueue è completa o 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 oppure il comando SIO_FLUSH in WSAIoctl viene eseguito in questo socket.

Commenti

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

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

Per evitare condizioni di gara, 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 Flags può essere usato per influenzare il comportamento della chiamata alla funzione RIOReceive 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 RIOReceive deve essere ottenuto in fase di esecuzione eseguendo una chiamata alla funzione WSAIoctlcon il SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode 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