LPFN_RIONOTIFY funzione di callback (mswsock.h)

La funzione RIONotify registra il metodo da usare per il comportamento di notifica con una coda di completamento I/O di I/O da usare con le estensioni di I/O registrate winsock.

Sintassi

LPFN_RIONOTIFY LpfnRionotify;

INT LpfnRionotify(
  RIO_CQ CQ
)
{...}

Parametri

CQ

Descrittore che identifica una coda di completamento di I/O.

Valore restituito

Se non si verifica alcun errore, la funzione RIONotify restituisce ERROR_SUCCESS. In caso contrario, la funzione non è riuscita e viene restituito un codice di errore specifico.

Codice restituito	Descrizione
WSAEINVAL	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se la coda di completamento non valida viene passata nel parametro CQ (ad esempio, RIO_INVALID_CQ). Questo errore può essere restituito anche quando si verifica un errore interno.
WSAEALREADY	Si è tentato di eseguire un'operazione su un socket non bloccato sul quale era già in corso un'operazione. Questo errore viene restituito se una richiesta RIONotify precedente non è ancora stata completata.

Commenti

La funzione RIONotify registra il metodo da usare per il comportamento di notifica per l'invio o la ricezione di dati di rete con le estensioni di I/O registrate da Winsock.

La funzione RIONotify è il meccanismo mediante il quale un'applicazione rileva che le richieste vengono completate e attendono una chiamata alla funzione RIODequeueCompletion . La funzione RIONotify imposta il metodo da usare per il comportamento di notifica quando una coda di completamento I/O non è vuota e contiene il completamento di un risultato.

Il comportamento di notifica per una coda di completamento viene impostato quando viene creato il RIO_CQ . La struttura RIO_NOTIFICATION_COMPLETION viene passata alla funzione RIOCreateCompletionQueue quando viene creata una RIO_CQ .

Per una coda di completamento che usa un evento, il membro Type della struttura RIO_NOTIFICATION_COMPLETION è impostato su RIO_EVENT_COMPLETION. Il membro Event.EventHandle deve contenere l'handle per un evento creato dalla funzione WSACreateEvent o CreateEvent . Per ricevere il completamento di RIONotify , l'applicazione deve attendere l'handle di evento specificato usando WSAWaitForMultipleEvents o una routine di attesa simile. Se l'applicazione prevede di reimpostare e riutilizzare l'evento, l'applicazione può ridurre il sovraccarico impostando il membro Event.NotifyReset su un valore diverso da zero. Ciò fa sì che l'evento venga reimpostato automaticamente dalla funzione RIONotify quando si verifica la notifica. Ciò riduce la necessità di chiamare la funzione WSAResetEvent per reimpostare l'evento tra le chiamate alla funzione RIONotify .

Quando la funzione RIONotify viene chiamata completamento eventi utilizzato e la coda di completamento specificata non è già vuota, l'evento viene impostato in modo sincrono o asincrono. In entrambi i casi, le voci aggiuntive non devono immettere la coda di completamento prima che l'evento venga impostato. Fino a quando la coda di completamento contiene il completamento di una richiesta che non ha impostato il flag RIO_MSG_DONT_NOTIFY , la coda di completamento viene considerata vuota ai fini della funzione RIONotify e l'evento non è impostato. Tutte le richieste completate possono comunque essere recuperate usando la funzione RIODequeueCompletion . Quando l'evento è impostato, l'applicazione chiama in genere la funzione RIODequeueCompletion per annullare la coda delle richieste di invio e ricezione completate.

Per una coda di completamento che usa una porta di completamento di I/O, il membro Type della struttura RIO_NOTIFICATION_COMPLETION è impostato su RIO_IOCP_COMPLETION. Il membro Iocp.IocpHandle deve contenere l'handle per una porta di completamento I/O creata dalla funzione CreateIoCompletionPort . Per ricevere il completamento rioNotify , l'applicazione deve chiamare la funzione GetQueuedCompletionStatus o GetQueuedCompletionStatusEx . L'applicazione deve fornire un oggetto OVERLAPPED dedicato per la coda di completamento e può anche usare il membro Iocp.CompletionKey per distinguere le richieste RIONotify sulla coda di completamento da altri completamenti di I/O, inclusi i completamenti RIONotify per altre code di completamento.

Un'applicazione che usa pool di thread può usare oggetti di attesa del pool di thread per ottenere i completamenti RIONotify tramite il pool di thread. In tal caso, la chiamata alla funzione SetThreadpoolWait deve seguire immediatamente la chiamata a RIONotify. Se la funzione SetThreadpoolWait viene chiamata prima di RIONotify e l'applicazione si basa su RIONotify per cancellare l'oggetto evento, ciò può comportare esecuzioni spurie del callback dell'oggetto wait.

Nota

Il puntatore di funzione alla funzione RIONotify deve essere ottenuto in fase di esecuzione effettuando una chiamata alla funzione WSAIoctl con il codice operativo 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 dello Store di Windows Phone 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.

Thread safety

Se più thread tentano di accedere alla stessa RIO_CQ usando la funzione RIODequeueCompletion , l'accesso deve essere coordinato da una sezione critica, da un blocco del writer lettore sottile o da un meccanismo di esclusione reciproca simile. Se le code di completamento non sono condivise, l'esclusione reciproca non è necessaria.

Requisiti

Requisito	Valore
Intestazione	mswsock.h