Funzione WSANSPIoctl (winsock2.h)

Articolo
08/27/2023

La funzione WSANSPIoctl di Windows Sockets consente agli sviluppatori di effettuare chiamate di controllo I/O a uno spazio dei nomi registrato.

Sintassi

INT WSAAPI WSANSPIoctl(
  [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
);

Parametri

[in] hLookup

L'handle di ricerca restituito da una chiamata precedente alla funzione WSALookupServiceBegin .

[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 di spazi dei nomi Network Location Awareness (NS_NLA). Questo IOCTL è definito nel file di intestazione Winsock2.h.

Valore	Significato
SIO_NSP_NOTIFY_CHANGE	Questa operazione verifica se i risultati restituiti con le chiamate precedenti usando il parametro hLookup sono ancora validi. Queste chiamate precedenti includono la chiamata iniziale alla funzione WSALookupServiceBegin per recuperare il parametro hLookup . Queste chiamate precedenti possono includere anche chiamate alla funzione WSALookupServiceNext usando il parametro hLookup .

[in] lpvInBuffer

Puntatore al buffer di input.

[in, out] cbInBuffer

Dimensioni, in byte, del buffer di input.

[out] lpvOutBuffer

Puntatore al buffer di output.

[in] cbOutBuffer

Dimensioni, in byte, del buffer di output.

[out] lpcbBytesReturned

Puntatore al numero di byte restituiti.

[in] lpCompletion

Puntatore a una struttura WSACOMPLETION usata per l'elaborazione asincrona. Impostare lpCompletion su NULL per forzare l'esecuzione del blocco (sincrono).

Valore restituito

Il successo restituisce NO_ERROR. L'errore restituisce SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando la funzione WSAGetLastError . La tabella seguente descrive i codici di errore.

Codice di errore	Descrizione
WSA_INVALID_HANDLE	Il parametro hLookup non è stato un handle di query valido restituito da WSALookupServiceBegin.
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSAEFAULT	LpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer o lpCompletion argomento 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.
WSAEINVAL	Un parametro fornito non è accettabile o l'operazione restituisce in modo inappropriato i risultati da più spazi dei nomi quando non ha senso per l'operazione specificata.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEOPNOTSUPP	L'operazione non è supportata. Questo errore viene restituito se il provider di spazi dei nomi non implementa questa funzione. Questo errore può essere restituito anche se il dwControlCode specificato è un comando non riconosciuto.
WSAEWOULDBLOCK	Il socket non usa l'I/O sovrapposto (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 WSANSPIoctl viene usata per impostare o recuperare parametri operativi associati a un handle di query a un provider di spazi dei nomi. Il parametro hLookup è un handle per la query del provider di spazi dei nomi restituita in precedenza dalla funzione WSALookupServiceBegin (non un handle socket).

Qualsiasi IOCTL inviato a un provider di spazi dei nomi può bloccare in modo indefinito, a seconda dell'implementazione dello spazio dei nomi. Se un'applicazione non può tollerare il blocco in una chiamata di funzione WSANSPIoctl , deve essere usata l/O sovrapposta e il parametro lpCompletion deve puntare a una struttura WSACOMPLETION . Per creare una chiamata di funzione WSANSPIoctl senza blocco e restituire immediatamente, impostare il membro Type della struttura WSACOMPLETION su NSP_NOTIFY_IMMEDIATELY.

Se lpCompletion è NULL, la funzione WSANSPIoctl viene eseguita come chiamata di blocco. Il provider di spazi dei nomi deve restituire immediatamente e non deve bloccare. Ma ogni spazio dei nomi è responsabile dell'applicazione di questo comportamento.

Il codice IOCTL seguente è supportato da diversi provider di spazio dei nomi Microsoft:

SIO_NSP_NOTIFY_CHANGE

Questa operazione verifica se i risultati restituiti con le chiamate precedenti usando il parametro hLookup sono ancora validi. Queste chiamate precedenti includono la chiamata iniziale alla funzione WSALookupServiceBegin per recuperare il parametro hLookup . Queste chiamate precedenti possono includere anche chiamate alla funzione WSALookupServiceNext usando il parametro hLookup .

I provider di spazi dei nomi Microsoft che supportano questo IOCTL includono quanto segue

NS_NLA : provider di spazi dei nomi NLA (Network Location Awareness).
NS_PNRPNAME : provider di spazi dei nomi PNRP (Peer Name Resolution Protocol).
NS_PNRPCLOUD : provider di spazi dei nomi cloud PNRP (Peer Name Resolution Protocol).

Altri provider di spazi dei nomi non Microsoft possono essere installati 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, NO_ERROR viene restituito che indica l'esito positivo nel polling per l'invalidazione del set di query.

Se il parametro lpCompletion non è NULL e punta a una struttura WSACOMPLETION , la funzione WSANSPIoctl 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 sono attualmente ignorati dai provider di spazi dei nomi Microsoft.

Per le applicazioni a thread singolo, un metodo tipico per usare la funzione WSANSPIoctl è il seguente. Chiamare la funzione WSANSPIoctl 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 WSALookupServiceNext per assicurarsi che i dati di query siano ancora validi. Se i dati non sono validi, chiamare la funzione WSALookupServiceEnd per chiudere l'handle di query. Chiamare la funzione WSALookupServiceBegin per recuperare un nuovo handle di query e avviare di nuovo la query.

Per le applicazioni multi thread, un metodo tipico per usare la funzione WSANSPIoctl è il seguente. Chiamare la funzione WSANSPIoctl con il parametro dwControlCode impostato su SIO_NSP_NOTIFY_CHANGE con una routine di completamento dopo la chiamata iniziale alla funzione WSALookupServiceBegin . L'applicazione userebbe 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 WSALookupServiceEnd per chiudere l'handle di query. Chiamare le funzioni WSALookupServiceBegin e WSANSPIoctl per recuperare un nuovo handle di query e avviare di nuovo la query.

Alcuni protocolli possono semplicemente memorizzare nella cache le informazioni in locale e invalidarla dopo qualche tempo, in cui la notifica può essere rilasciata 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 in cui è stata richiesta e rilasciata la notifica delle modifiche.

Le operazioni di polling immediato sono in genere molto meno costose perché non richiedono un oggetto di notifica. Nella maggior parte dei casi, questa operazione viene implementata come un semplice controllo variabile booleano. 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 di spazi dei nomi e comporta un sovraccarico di elaborazione correlato all'oggetto di notifica coinvolto nel segnalare l'evento di modifica.

Per annullare una richiesta di notifica asincrona, terminare la query originale con una chiamata di funzione WSALookupServiceEnd nell'handle di query interessato. L'annullamento della notifica asincrona per LUP_NOTIFY_HWND non pubblica alcun messaggio, tuttavia, verrà completata un'operazione sovrapposta e verrà recapitata una notifica con l'errore WSA_OPERATION_ABORTED.

Nota Tutti gli I/O avviati da un determinato thread vengono annullati quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono non riuscire se il thread viene chiuso prima del completamento delle operazioni. Per altre informazioni, vedere ExitThread .

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
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h