使用 IRP 搭配 Winsock 核心函式

發行項
03/17/2025

Winsock 核心（WSK）網路程式設計介面（NPI）使用 IRP 來異步完成網路 I/O 作業。每個 WSK 函式都會以 IRP 的指標作為參數。 WSK 子系統會在 WSK 函式執行完作業後完成 IRP。

WSK 應用程式用來傳遞至 WSK 函式的 IRP 可以透過下列其中一種方式產生。

WSK 應用程式會呼叫 IoAllocateIrp 函式來設定 IRP。在此情況下，WSK 應用程式必須配置至少一個 I/O 堆疊位置的 IRP。
WSK 應用程式會重複使用先前配置已完成的 IRP。在此情況下，WSK 必須呼叫 IoReuseIrp 函式，才能重新初始化 IRP。
WSK 應用程式會使用由較高層級驅動程式或 I/O 管理員傳遞給它的 IRP。在此情況下，IRP 必須至少有一個剩餘的 I/O 堆棧位置可供 WSK 子系統使用。

在 WSK 應用程式獲得 IRP 用於呼叫 WSK 函式後，可以為 IRP 設定一個 IoCompletion 例程，以便在 WSK 子系統完成 IRP 時調用該 IRP。 WSK 應用程式會藉由呼叫 IoSetCompletionRoutine 函式，為 IRP 設定 IoCompletion 例程。視 IRP 的產生方式而定，IoCompletion 例程是必要或選擇性的。

如果 WSK 應用程式已設定 IRP，或重複使用先前配置的 IRP，則必須先為 IRP 設定 IoCompletion 例程，再呼叫 WSK 函式。在此情況下，WSK 應用程式必須針對 InvokeOnSuccess指定 TRUE、InvokeOnError，以及 InvokeOnCancel 參數，這些參數會傳遞至 IoSetCompletionRoutine 函式，以確保一律會呼叫 IoCompletion 例程。此外，為 IRP 設定的 IoCompletion 例程必須一律傳回STATUS_MORE_PROCESSING_REQUIRED，以終止 IRP 的完成處理。如果在呼叫 IoCompletion 例程後，WSK 應用程式已透過 IRP 完成，則應在從 IoCompletion 例程返回之前，呼叫 IoFreeIrp 函式來釋放 IRP。如果 WSK 應用程式沒有釋放 IRP，則可以重複使用 IRP 來呼叫另一個 WSK 函式。
如果 WSK 應用程式使用由較高層級驅動程式或 I/O 管理員向下傳遞的 IRP，只有在必須在 WSK 函式執行的作業完成時需要通知的情況下，才應該在呼叫 WSK 函式之前，為該 IRP 設定 IoCompletion 例程。如果 WSK 應用程式沒有為 IRP 設定 IoCompletion 例程，則當 IRP 完成時，按照一般 IRP 完成程序，IRP 會被傳回較高層級的驅動程式或 I/O 管理員。如果 WSK 應用程式為 IRP 設定 IoCompletion 例程，那麼 IoCompletion 例程可以傳回 STATUS_SUCCESS 或 STATUS_MORE_PROCESSING_REQUIRED。如果 IoCompletion 例程傳回STATUS_SUCCESS，IRP 完成處理會正常繼續。如果 IoCompletion 例程傳回STATUS_MORE_PROCESSING_REQUIRED，WSK 應用程式必須在完成處理 WSK 函式所執行之作業的結果之後，呼叫 IoCompleteRequest 來完成 IRP。 WSK 應用程式絕對不應該釋放任何由高階驅動程式或 I/O 管理器傳遞給它的 IRP。

注意如果 WSK 應用程式為由較高層級的驅動程式或 I/O 管理器傳遞過來的 IRP 設定了 IoCompletion 例程，則該 IoCompletion 例程必須檢查該 IRP 的 PendingReturned 成員，若 PendingReturned 成員為 TRUE，則呼叫 IoMarkIrpPending 函式。如需詳細資訊，請參閱實作IoCompletion例程。

注意 WSK 應用程式不應該在 IoCompletion 例程中呼叫新的 WSK 函式。這樣做可能會導致遞歸呼叫並耗盡核心模式堆疊。在 IRQL = DISPATCH_LEVEL執行時，這也會導致其他線程耗盡。

WSK 應用程式不會初始化傳遞至 WSK 函式的 IRP，但會設定 IoCompletion 例行程序。當 WSK 應用程式將 IRP 傳遞至 WSK 函式時，WSK 子系統會代表應用程式設定下一個 I/O 堆疊位置。

下列程式代碼範例示範 WSK 應用程式如何在套接字上執行接收作業時配置和使用 IRP。

// Prototype for the receive IoCompletion routine
NTSTATUS
  ReceiveComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    );

// Function to receive data
NTSTATUS
  ReceiveData(
    PWSK_SOCKET Socket,
    PWSK_BUF DataBuffer
    )
{
  PWSK_PROVIDER_CONNECTION_DISPATCH Dispatch;
  PIRP Irp;
  NTSTATUS Status;

  // Get pointer to the 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,
    ReceiveComplete,
    DataBuffer,  // Use the data buffer for the context
    TRUE,
    TRUE,
    TRUE
    );

  // Initiate the receive operation on the socket
  Status =
    Dispatch->WskReceive(
      Socket,
      DataBuffer,
      0,  // No flags are specified
      Irp
      );

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

// Receive IoCompletion routine
NTSTATUS
  ReceiveComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    )
{
  UNREFERENCED_PARAMETER(DeviceObject);

  PWSK_BUF DataBuffer;
  ULONG ByteCount;

  // Check the result of the receive operation
  if (Irp->IoStatus.Status == STATUS_SUCCESS)
  {
    // Get the pointer to the data buffer
    DataBuffer = (PWSK_BUF)Context;
 
    // Get the number of bytes received
    ByteCount = (ULONG)(Irp->IoStatus.Information);

    // Process the received data
    ...
  }

  // 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;
}

上一個範例中顯示的模型，其中 WSK 應用程式會配置 IRP，然後在完成例程中釋放它，是範例中在整個 WSK 檔其餘部分中使用的模型。

下列程式代碼範例示範 WSK 應用程式如何在套接字上執行接收作業時，使用由較高層級驅動程式或 I/O 管理員傳遞給它的 IRP。

// Prototype for the receive IoCompletion routine
NTSTATUS
  ReceiveComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    );

// Function to receive data
NTSTATUS
  ReceiveData(
    PWSK_SOCKET Socket,
    PWSK_BUF DataBuffer,
    PIRP Irp;  // IRP from a higher level driver or the I/O manager
    )
{
  PWSK_PROVIDER_CONNECTION_DISPATCH Dispatch;
  NTSTATUS Status;

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

  // Set the completion routine for the IRP such that it is
  // only called if the receive operation succeeds.
  IoSetCompletionRoutine(
    Irp,
    ReceiveComplete,
    DataBuffer,  // Use the data buffer for the context
    TRUE,
    FALSE,
    FALSE
    );

  // Initiate the receive operation on the socket
  Status =
    Dispatch->WskReceive(
      Socket,
      DataBuffer,
      0,  // No flags are specified
      Irp
      );

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

// Receive IoCompletion routine
NTSTATUS
  ReceiveComplete(
    PDEVICE_OBJECT DeviceObject,
    PIRP Irp,
    PVOID Context
    )
{
  UNREFERENCED_PARAMETER(DeviceObject);

  PWSK_BUF DataBuffer;
  ULONG ByteCount;

  // Since the completion routine was only specified to
  // be called if the operation succeeds, this should
  // always be true.
  ASSERT(Irp->IoStatus.Status == STATUS_SUCCESS);

  // Check the pending status of the IRP
  if (Irp->PendingReturned == TRUE)
  {
    // Mark the IRP as pending
    IoMarkIrpPending(Irp);
  }

  // Get the pointer to the data buffer
  DataBuffer = (PWSK_BUF)Context;
 
  // Get the number of bytes received
  ByteCount = (ULONG)(Irp->IoStatus.Information);

  // Process the received data
  ...

  // Return STATUS_SUCCESS to continue the
  // completion processing of the IRP.
  return STATUS_SUCCESS;
}

如需使用 IRP 的詳細資訊，請參閱處理 IRP。

共用方式為

使用 IRP 搭配 Winsock 核心函式

意見反應

其他資源