PFN_WSK_CONTROL_SOCKET funzione di callback (wsk.h)

Articolo
02/27/2024

La funzione WskControlSocket esegue operazioni di controllo su un socket.

Sintassi

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Parametri

[in] Socket

Puntatore a una struttura WSK_SOCKET che specifica l'oggetto socket per il socket in cui viene eseguita l'operazione di controllo.

[in] RequestType

Valore che specifica il tipo di operazione di controllo eseguita. Un'applicazione WSK imposta questo parametro su uno dei valori seguenti:

WskSetOption

Impostare lo stato o il valore per un'opzione socket.

WskGetOption

Ottenere lo stato o il valore di un'opzione socket.

WskIoctl

Eseguire un'operazione di controllo I/O.

[in] ControlCode

Se il parametro RequestType è impostato su WskSetOption o WskGetOption, il parametro ControlCode specifica l'opzione socket specifica il cui valore viene impostato o recuperato. Per altre informazioni sulle opzioni socket supportate dal sottosistema WSK, vedere Opzioni socket WSK. Il protocollo di rete sottostante potrebbe supportare opzioni di socket aggiuntive.

Se il parametro RequestType è impostato su WskIoctl, il parametro ControlCode specifica l'operazione di controllo I/O specificata eseguita. Per altre informazioni sulle operazioni di controllo I/O supportate dal sottosistema WSK, vedere Operazioni IOCTL di WSK Socket. Il protocollo di rete sottostante potrebbe supportare operazioni di controllo di I/O socket aggiuntive.

[in] Level

Livello nello stack di rete in cui viene impostato o recuperato il valore di un'opzione socket. Per le opzioni del socket a livello di sottosistema WSK, l'applicazione WSK deve impostare questo parametro su SOL_SOCKET. Per le opzioni socket del protocollo di trasporto o del protocollo di rete, l'applicazione WSK deve impostare questo parametro sul livello appropriato per il trasporto sottostante.

Se il parametro RequestType è impostato su WskIoctl, il parametro Level viene ignorato.

[in] InputSize

Numero di byte di dati nel buffer a cui fa riferimento il parametro InputBuffer .

[in, optional] InputBuffer

Buffer allocato dal chiamante che fornisce tutti i dati di input necessari per eseguire l'operazione di controllo specificata. Se non sono necessari dati di input per l'operazione di controllo specificata, l'applicazione WSK deve impostare questo parametro su NULL e impostare il parametro InputSize su zero.

[in] OutputSize

Dimensioni del buffer a cui punta il parametro OutputBuffer .

[out, optional] OutputBuffer

Buffer allocato dal chiamante che riceve tutti i dati di output restituiti dall'operazione di controllo specificata. Se non vengono restituiti dati di output dall'operazione di controllo specificata, l'applicazione WSK deve impostare questo parametro su NULL e impostare il parametro OutputSize su zero.

[out, optional] OutputSizeReturned

Puntatore a una variabile tipizzata ULONG che riceve il numero di byte di dati restituiti nel buffer a cui fa riferimento il parametro OutputBuffer . Un'applicazione WSK deve impostare il parametro OutputSizeReturned su NULL , ad eccezione del fatto che tutte le operazioni seguenti sono vere:

Il parametro Irp è impostato su NULL.
L'operazione eseguita restituisce i dati di output nel buffer a cui fa riferimento il parametro OutputBuffer .
Il numero di byte di dati di output restituiti dall'operazione eseguita è sconosciuto.

[in, out] Irp

Puntatore a un chiamante allocato IRP usato dal sottosistema WSK per completare l'operazione di controllo in modo asincrono. Per altre informazioni sull'uso di IRP con funzioni WSK, vedere Uso di IRP con Funzioni kernel Winsock.

Se il parametro RequestType è impostato su WskSetOption o WskGetOption, il parametro Irp è obbligatorio, è facoltativo o deve essere NULL a seconda dell'opzione del socket specifica impostata o recuperata. Per altre informazioni sui requisiti per il parametro Irp per ognuna delle opzioni di socket supportate, vedere Opzioni socket WSK.

Se il parametro RequestType è impostato su WskIoctl, il parametro Irp è obbligatorio, è facoltativo o deve essere NULL a seconda dell'operazione di controllo I/O specifica che viene eseguita. Per altre informazioni sui requisiti per il parametro Irp per ognuna delle operazioni di controllo I/O supportate, vedere Operazioni IOCTL di WSK Socket.

Valore restituito

WskControlSocket restituisce uno dei codici NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Operazione di controllo completata correttamente. Se l'applicazione WSK ha specificato un puntatore a un'IRP nel parametro IRP , l'IRP verrà completato con lo stato di esito positivo e il numero di byte restituiti nel buffer a cui punta il parametro OutputBuffer verrà restituito nel campo IoStatus.Information dell'IRP .
STATUS_PENDING	Il sottosistema WSK non è riuscito a completare immediatamente l'operazione di controllo. Il sottosistema WSK completerà l'IRP dopo aver completato l'operazione di controllo. Lo stato dell'operazione di controllo verrà restituito nel campo IoStatus.Status dell'IRP . Se l'operazione ha esito positivo, il numero di byte restituiti nel buffer a cui fa riferimento il parametro OutputBuffer verrà restituito nel campo IoStatus.Information dell'IRP .
STATUS_EVENT_PENDING	Il sottosistema WSK non è riuscito a completare immediatamente l'operazione di controllo. Questo valore viene restituito solo quando un'applicazione WSK disabilita una funzione di callback evento in un socket quando sono attualmente presenti chiamate in corso a tale funzione di callback evento e quando il parametro Irp è NULL. Per altre informazioni sulla disabilitazione delle funzioni di callback degli eventi, vedere SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	Il socket non è più funzionale. L'IRP verrà completato con lo stato di errore. L'applicazione WSK deve chiamare la funzione WskCloseSocket per chiudere il socket il prima possibile.
Altri codici di stato	Si è verificato un errore. L'IRP verrà completato con lo stato di errore.

Commenti

Se un'applicazione WSK specifica WskSetOption o WskGetOption nel parametro RequestType , vedere Opzioni socket WSK per altre informazioni sul modo in cui vengono usati i buffer di input e output per ogni opzione socket.

Se un'applicazione WSK specifica WskIoctl nel parametro RequestType , vedere Operazioni IOCTL WSK Socket per altre informazioni sul modo in cui vengono usati i buffer di input e output per ogni operazione di controllo I/O.

Se la funzione WskControlSocket restituisce STATUS_PENDING, tutti i buffer a cui punta il parametro InputBuffer o il parametro OutputBuffer devono rimanere validi fino al completamento dell'IRP. Se l'applicazione WSK ha allocato i buffer con una delle funzioni ExAllocateXxx , non può liberare la memoria con la funzione ExFreeXxx corrispondente fino al completamento dell'IRP. Se l'applicazione WSK ha allocato i buffer nello stack, non può restituire dalla funzione che chiama la funzione WskControlSocket fino al completamento dell'IRP.

I chiamanti della funzione WskControlSocket devono essere eseguiti in IRQL = DISPATCH_LEVEL tranne quando il parametro RequestType è impostato su WskIoctl<e il parametro ControlCode è impostato su SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE o SIO_ADDRESS_LIST_SORT. In questa situazione, i chiamanti devono essere in esecuzione in IRQL = PASSIVE_LEVEL.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
Piattaforma di destinazione	Universale
Intestazione	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL (vedere sezione Osservazioni)