Funzione di callback LPNSPIOCTL (ws2spi.h)
La funzione NSPIoctl invia un IOCTL a un provider di servizi dello spazio dei nomi.
Sintassi
LPNSPIOCTL Lpnspioctl;
INT Lpnspioctl(
[in] HANDLE hLookup,
[in] DWORD dwControlCode,
[in] LPVOID lpvInBuffer,
[in, out] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSACOMPLETION lpCompletion,
[in] LPWSATHREADID lpThreadId
)
{...}
Parametri
[in] hLookup
Handle di ricerca restituito da una chiamata precedente alla funzione NSPLookupServiceBegin .
[in] dwControlCode
Codice di controllo dell'operazione da eseguire.
I valori che possono essere usati per il parametro dwControlCode sono determinati dal provider dello spazio dei nomi.
Il valore seguente è supportato da diversi provider di spazi dei nomi Microsoft, tra cui il provider dello spazio dei nomi Network Location Awareness (NS_NLA). Questo IOCTL è definito nel file di intestazione Winsock2.h.
| Valore | Significato |
|---|---|
|
Questa operazione controlla se i risultati restituiti con le chiamate precedenti che usano il parametro hLookup sono ancora validi. Queste chiamate precedenti includono la chiamata iniziale alla funzione NSPLookupServiceBegin per recuperare il parametro hLookup . Queste chiamate precedenti possono includere anche chiamate alla funzione NSPLookupServiceNext usando il parametro hLookup . |
[in] lpvInBuffer
Puntatore al buffer di input.
[in, out] cbInBuffer
Dimensione, in byte, del buffer di input.
[out] lpvOutBuffer
Puntatore al buffer di output.
[in] cbOutBuffer
Dimensione, in byte, del buffer di output.
[out] lpcbBytesReturned
Puntatore al numero di byte restituiti.
[in] lpCompletion
Puntatore a una struttura WSACOMPLETION , utilizzata per l'elaborazione asincrona. Impostare lpCompletion su NULL per forzare l'esecuzione del blocco (sincrono).
[in] lpThreadId
Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID di riferimento (non il puntatore) fino a quando non viene restituita la funzione WPUQueueApc .
Valore restituito
Se non si verifica alcun errore e l'operazione è stata completata immediatamente, la funzione NSPIoctl deve restituire NO_ERROR (zero). Si noti che in questo caso la routine di completamento, se specificata, sarà già stata accodata.
La funzione NSPIoctl deve restituire SOCKET_ERROR (ovvero 1) se la routine ha esito negativo e deve impostare il codice di errore appropriato usando WSASetLastError.
Il codice di errore WSA_IO_PENDING indica che un'operazione sovrapposta è stata avviata correttamente e che il completamento verrà indicato in un secondo momento. Qualsiasi altro codice di errore indica che non è stata avviata alcuna operazione sovrapposta e che non si verificherà alcuna indicazione di completamento.
| Codice di errore | Descrizione |
|---|---|
| Il parametro hLookup non è un handle di query valido restituito da NSPLookupServiceBegin. | |
| Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento. | |
| L'argomento lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer o lpCompletion non è totalmente contenuto in una parte valida dello spazio indirizzi utente. In alternativa, l'argomento cbInBuffer o cbOutBuffer è troppo piccolo e l'argomento viene modificato per riflettere le dimensioni di allocazione necessarie. | |
| Un parametro specificato non è accettabile o l'operazione restituisce in modo non appropriato risultati da più spazi dei nomi quando non ha senso per l'operazione specificata. | |
| Il sottosistema di rete non è riuscito. | |
| L'operazione non è supportata. Questo errore viene restituito se il provider dello spazio dei nomi non implementa questa funzione. Questo errore può essere restituito anche se il valore dwControlCode specificato è un comando non riconosciuto. | |
|
La risorsa non è temporaneamente disponibile. Il socket non usa operazioni di I/O sovrapposte (elaborazione asincrona), ma il parametro lpCompletion non è null**.
Questo errore viene usato come notifica speciale per il SIO_NSP_NOTIFY_CHANGE IOCTL quando il parametro lpCompletion è NULL (un poll) per indicare che un set di query rimane valido. |
Commenti
La funzione NSPIoctl viene usata per inviare un codice di controllo I/O a un provider di spazi dei nomi per impostare o recuperare i parametri operativi associati a un handle di query. Il parametro hLookup è un handle per la query del provider dello spazio dei nomi restituita in precedenza dalla funzione NSPLookupServiceBegin (non un handle socket).
Qualsiasi IOCTL inviato a un provider di spazi dei nomi può bloccarsi a tempo indefinito, a seconda dell'implementazione dello spazio dei nomi. Se un'applicazione non può tollerare il blocco in una chiamata di funzione NSPIoctl , è necessario usare le operazioni di I/O sovrapposte e il parametro lpCompletion deve puntare a una struttura WSACOMPLETION . Per chiamare immediatamente un NSPIoctl function nonblocking e restituire immediatamente, impostare il membro Type della struttura WSACOMPLETION su NSP_NOTIFY_IMMEDIATELY.
Se lpCompletion è NULL, la funzione NSPIoctl viene eseguita come chiamata di blocco. Il provider dello spazio dei nomi deve restituire immediatamente e non deve bloccare. Tuttavia, ogni provider di spazi dei nomi è responsabile dell'applicazione di questo comportamento.
Il codice IOCTL seguente è supportato da diversi provider di spazi dei nomi Microsoft:
I provider di spazi dei nomi Microsoft che supportano questo IOCTL includono quanto segue:
- NS_NLA: provider dello spazio dei nomi NLA (Network Location Awareness).
- NS_PNRPNAME: provider dello spazio dei nomi PNRP (Peer Name Resolution Protocol).
- NS_PNRPCLOUD: provider di spazi dei nomi cloud PNRP (Peer Name Resolution Protocol).
È possibile installare altri provider di spazi dei nomi non Microsoft che supportano anche questo IOCTL.
Quando il parametro lpCompletion è NULL, questo IOCTL implementa un comportamento speciale. Se il parametro lpCompletion è NULL per questo IOCTL, questa operazione è un polling e restituisce immediatamente. Se il set di query rimane valido, WSAEWOULDBLOCK viene restituito come notifica che il set di query rimane valido. Se il set di query è stato modificato e non è valido, viene restituito NO_ERROR che indica l'esito positivo del polling per invalidazione del set di query.
Se il parametro lpCompletion non è NULL e punta a una struttura WSACOMPLETION , la funzione NSPIoctl restituisce WSA_IO_PENDING se l'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento. Il metodo specificato nella struttura WSACOMPLETION viene usato per notificare all'applicazione se il set di query è ancora valido.
Non tutti i protocolli di risoluzione dei nomi sono in grado di supportare questa funzionalità e pertanto questa chiamata di funzione potrebbe non riuscire con WSAEOPNOTSUPP. Una query contenente dati da più provider non può chiamare questo IOCTL e restituirà WSAEINVAL.
I parametri lpvInBuffer, cbInBuffer, lpvOutBuffer e cbOutBuffer vengono attualmente ignorati dai provider di spazi dei nomi Microsoft.
Per le applicazioni a thread singolo, un metodo tipico per usare la funzione NSPIoctl è il seguente. Chiamare la funzione NSPIoctl con il parametro dwControlCode impostato su SIO_NSP_NOTIFY_CHANGE senza routine di completamento (il parametro lpCompletion impostato su NULL) dopo ogni chiamata di funzione NSPLookupServiceNext per assicurarsi che i dati della query siano ancora validi. Se i dati non sono validi, chiamare la funzione NSPLookupServiceEnd per chiudere l'handle di query. Chiamare la funzione NSPLookupServiceBegin per recuperare un nuovo handle di query e avviare nuovamente la query.
Per le applicazioni multithreading, un metodo tipico per usare la funzione NSPIoctl è il seguente. Chiamare la funzione NSPIoctl con il parametro dwControlCode impostato su SIO_NSP_NOTIFY_CHANGE con una routine di completamento dopo la chiamata iniziale alla funzione NSPLookupServiceBegin . L'applicazione userà il meccanismo per la notifica specificata nella routine di completamento per ricevere una notifica quando i dati non sono più validi. Un meccanismo comune consiste nell'usare un evento specificato nella routine di completamento. Se i dati non sono validi, chiamare la funzione NSPLookupServiceEnd per chiudere l'handle di query. Chiamare le funzioni NSPLookupServiceBegin e NSPIoctl per recuperare un nuovo handle di query e avviare nuovamente la query.
Alcuni protocolli possono semplicemente memorizzare nella cache le informazioni in locale e invalidarla dopo qualche tempo, nel qual caso potrebbe essere inviata una notifica per indicare che la cache locale è stata invalidata.
Per i protocolli di risoluzione dei nomi in cui le modifiche non sono frequenti, è possibile che un provider di spazi dei nomi indichi un evento di modifica globale che potrebbe non essere applicabile alla query su cui è stata richiesta e inviata la notifica di modifica.
Le operazioni di polling immediato sono in genere molto meno a elevato utilizzo di risorse perché non richiedono un oggetto di notifica. Nella maggior parte dei casi, questa operazione viene implementata come semplice controllo di variabile booleana. La notifica asincrona, tuttavia, può richiedere la creazione di thread di lavoro dedicati e/o canali di comunicazione tra processi, a seconda dell'implementazione del servizio provider dello spazio dei nomi e comporta un sovraccarico di elaborazione correlato all'oggetto notifica coinvolto nella segnalazione dell'evento di modifica.
Per annullare una richiesta di notifica asincrona, terminare la query originale con una chiamata di funzione NSPLookupServiceEnd sull'handle di query interessato. L'annullamento della notifica asincrona per LUP_NOTIFY_HWND non insedierà alcun messaggio, ma verrà completata un'operazione sovrapposta e la notifica verrà recapitata con l'errore WSA_OPERATION_ABORTED.
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ws2spi.h |