Abilitazione e disabilitazione delle funzioni di callback degli eventi

Un'applicazione WSK (Winsock Kernel) può implementare funzioni di callback degli eventi chiamate dal sottosistema WSK in modo asincrono per notificare all'applicazione quando si verificano determinati eventi in un socket. Un'applicazione WSK può fornire una struttura di tabella dispatch client al sottosistema WSK ogni volta che crea un socket o accetta un socket in un socket in ascolto. Questa tabella dispatch contiene puntatori alle funzioni di callback degli eventi dell'applicazione WSK per il nuovo socket. Se un'applicazione WSK non implementa funzioni di callback di eventi per un socket specifico, non è necessario fornire una struttura di tabella dispatch client al sottosistema WSK per tale socket.

Tutte le funzioni di callback degli eventi di un socket, ad eccezione delle funzioni di callback degli eventi WskInspectEvent e WskAbortEvent di un socket di ascolto, possono essere abilitate o disabilitate usando l'opzione socket SO_WSK_EVENT_CALLBACK . Un'applicazione WSK può abilitare più funzioni di callback di eventi in un socket contemporaneamente. Tuttavia, un'applicazione WSK deve disabilitare singolarmente ogni funzione di callback degli eventi.

L'esempio di codice seguente illustra come un'applicazione WSK può usare l'opzione socket SO_WSK_EVENT_CALLBACK per abilitare le funzioni di callback degli eventi WskDisconnectEvent e WskReceiveEvent in un socket orientato alla connessione.

// Function to enable the WskDisconnectEvent and WskReceiveEvent
// event callback functions on a connection-oriented socket
NTSTATUS
  EnableDisconnectAndRecieveCallbacks(
    PWSK_SOCKET Socket
    )
{
  PWSK_PROVIDER_CONNECTION_DISPATCH Dispatch;
  WSK_EVENT_CALLBACK_CONTROL EventCallbackControl;
  NTSTATUS Status;

  // Get pointer to the socket's provider dispatch structure
  Dispatch =
    (PWSK_PROVIDER_CONNECTION_DISPATCH)(Socket->Dispatch);

  // Specify the WSK NPI identifier
  EventCallbackControl.NpiId = &NPI_WSK_INTERFACE_ID;

  // Set the event flags for the event callback functions that
  // are to be enabled on the socket
  EventCallbackControl.EventMask =
    WSK_EVENT_DISCONNECT | WSK_EVENT_RECEIVE;

  // Initiate the control operation on the socket
  Status =
    Dispatch->WskControlSocket(
      Socket,
      WskSetOption,
      SO_WSK_EVENT_CALLBACK,
      SOL_SOCKET,
      sizeof(WSK_EVENT_CALLBACK_CONTROL),
      &EventCallbackControl,
      0,
      NULL,
      NULL,
      NULL  // No IRP for this control operation
      );

  // Return the status of the call to WskControlSocket()
  return Status;
}

L'esempio di codice seguente illustra come un'applicazione WSK può usare l'opzione socket SO_WSK_EVENT_CALLBACK per disabilitare le funzioni di callback degli eventi WskReceiveEvent in un socket orientato alla connessione.

// Prototype for the disable disconnect IoCompletion routine
NTSTATUS
  DisableDisconnectComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    );

// Function to disable the WskDisconnectEvent event
// callback functions on a connection-oriented socket
NTSTATUS
  DisableDisconnectCallback(
    PWSK_SOCKET Socket
    )
{
  PWSK_PROVIDER_CONNECTION_DISPATCH Dispatch;
  PIRP Irp;
  WSK_EVENT_CALLBACK_CONTROL EventCallbackControl;
  NTSTATUS Status;

  // Get pointer to the socket's provider dispatch structure
  Dispatch =
    (PWSK_PROVIDER_CONNECTION_DISPATCH)(Socket->Dispatch);

  // Allocate an IRP
  Irp =
    IoAllocateIrp(
      1,
      FALSE
      );

  // Check result
  if (!Irp)
  {
    // Return error
    return STATUS_INSUFFICIENT_RESOURCES;
  }

  // Set the completion routine for the IRP
  IoSetCompletionRoutine(
    Irp,
 DisableDisconnectComplete,
    Socket,  // Use the socket object for the context
    TRUE,
    TRUE,
    TRUE
    );

  // Specify the WSK NPI identifier
  EventCallbackControl.NpiId = &NPI_WSK_INTERFACE_ID;

  // Set the event flag for the event callback function that
  // is to be disabled on the socket along with the disable flag
  EventCallbackControl.EventMask =
    WSK_EVENT_DISCONNECT | WSK_EVENT_DISABLE;

  // Initiate the control operation on the socket
  Status =
    Dispatch->WskControlSocket(
      Socket,
      WskSetOption,
      SO_WSK_EVENT_CALLBACK,
      SOL_SOCKET,
      sizeof(WSK_EVENT_CALLBACK_CONTROL),
      &EventCallbackControl,
      0,
      NULL,
      NULL,
      Irp
      );

  // Return the status of the call to WskControlSocket()
  return Status;
}

// Disable disconnect IoCompletion routine
NTSTATUS
  DisableDisconnectComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    )
{
  UNREFERENCED_PARAMETER(DeviceObject);

  PWSK_SOCKET Socket;

  // Check the result of the control operation
  if (Irp->IoStatus.Status == STATUS_SUCCESS)
  {
    // The WskDisconnectEvent event callback
    // function is now disabled

    // Get the socket object from the context
    Socket = (PWSK_SOCKET)Context;

    // Perform the next operation on the socket
    ...
  }

  // Error status
  else
  {
    // Handle error
    ...
  }

  // Free the IRP
  IoFreeIrp(Irp);

  // Always return STATUS_MORE_PROCESSING_REQUIRED to
  // terminate the completion processing of the IRP.
  return STATUS_MORE_PROCESSING_REQUIRED;
}

Per i socket di ascolto, le funzioni di callback degli eventi WskInspectEvent e WskAbortEvent vengono abilitate solo se l'applicazione WSK abilita la modalità di accettazione condizionale nel socket. Un'applicazione WSK abilita la modalità di accettazione condizionale su un socket di ascolto impostando l'opzione socket SO_CONDITIONAL_ACCEPT per il socket prima di associarlo a un indirizzo di trasporto locale. Per altre informazioni su come impostare le opzioni socket, vedere Esecuzione di operazioni di controllo su un socket.

Dopo l'abilitazione della modalità di accettazione condizionale in un socket in ascolto, le funzioni di callback degli eventi WskInspectEvent e WskAbortEvent del socket non possono essere disabilitate. Per altre informazioni sull'accettazione condizionale delle connessioni in ingresso nei socket in ascolto, vedere Ascolto e accettazione di connessioni in ingresso.

Un socket di ascolto può abilitare automaticamente le funzioni di callback degli eventi sui socket orientati alla connessione accettati dalla funzione di callback dell'evento WskAcceptEvent del socket di ascolto. Un'applicazione WSK abilita automaticamente queste funzioni di callback abilitando le funzioni di callback degli eventi socket orientate alla connessione nel socket di ascolto. Per altre informazioni su questo processo, vedere SO_WSK_EVENT_CALLBACK.

Se un'applicazione WSK abilita sempre determinate funzioni di callback degli eventi in ogni socket creato, l'applicazione può configurare il sottosistema WSK per abilitare automaticamente tali funzioni di callback degli eventi usando l'operazione di controllo client WSK_SET_STATIC_EVENT_CALLBACKS . Le funzioni di callback degli eventi abilitate in questo modo sono sempre abilitate e non possono essere disabilitate o riabilitate in un secondo momento dall'applicazione WSK. Se un'applicazione WSK abilita sempre determinate funzioni di callback di eventi in ogni socket creato, l'applicazione deve usare questo metodo per abilitare automaticamente tali funzioni di callback degli eventi perché produrrà prestazioni molto migliori.

Nell'esempio di codice seguente viene illustrato come un'applicazione WSK può usare l'operazione di controllo client WSK_SET_STATIC_EVENT_CALLBACKS per abilitare automaticamente la funzione di callback dell'evento WskReceiveFromEvent nei socket di datagrammi e la funzione di callback dell'evento WskReceiveEvent sui socket orientati alla connessione.

// Function to set static event callbacks
NTSTATUS
  SetStaticEventCallbacks(
    PWSK_APP_BINDING_CONTEXT BindingContext,
    )
{
  WSK_EVENT_CALLBACK_CONTROL EventCallbackControl;
  NTSTATUS Status;

  // Specify the WSK NPI identifier
  EventCallbackControl.NpiId = &NPI_WSK_INTERFACE_ID;

  // Set the event flags for the event callback functions that
  // are to be automatically enabled on every new socket
  EventCallbackControl.EventMask =
    WSK_EVENT_RECEIVE_FROM | WSK_EVENT_RECEIVE;

  // Perform client control operation
  Status =
    BindingContext->
      WskProviderDispatch->
        WskControlClient(
          BindingContext->WskClient,
          WSK_SET_STATIC_EVENT_CALLBACKS,
          sizeof(WSK_EVENT_CALLBACK_CONTROL),
          &EventCallbackControl,
          0,
          NULL,
          NULL,
          NULL  // No IRP for this control operation
          );

  // Return status of client control operation
  return Status;
}

Se un'applicazione WSK usa l'operazione di controllo client WSK_SET_STATIC_EVENT_CALLBACKS per abilitare automaticamente determinate funzioni di callback degli eventi, è necessario farlo prima di creare qualsiasi socket.