WdfIoTargetFormatRequestForInternalIoctlOthers 函式 (wdfiotarget.h)

發行項
02/27/2024

[僅適用於 KMDF]

WdfIoTargetFormatRequestForInternalIoctlOthers 方法會建置 I/O 目標的非標準內部設備控制要求，但不會傳送要求。

語法

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

參數

[in] IoTarget

從先前呼叫 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 取得的本機或遠端 I/O 目標物件的句柄，或從特製化 I/O 目標提供的方法取得。

[in] Request

架構要求物件的句柄。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] IoctlCode

I/O 目標支援的 I/O 控制項程式代碼 (IOCTL) 。

[in, optional] OtherArg1

架構記憶體物件的句柄。這個物件代表驅動程式用於要求特定、驅動程式定義內容資訊的緩衝區。如需詳細資訊，請參閱接下來的＜備註＞一節。這個參數是選擇性的，而且可以是 NULL。

[in, optional] OtherArg1Offset

呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性位元移和長度值。驅動程式可以使用這些值來指定 OtherArg1 所指定之內容區域區段的開始地址和長度。這個參數是選擇性的，而且可以是 NULL。

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性位元移和長度值。驅動程式可以使用這些值來指定 OtherArg2 所指定之內容區域的開頭位址和長度。這個參數是選擇性的，而且可以是 NULL。

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性位元移和長度值。驅動程式可以使用這些值來指定 OtherArg4 所指定內容區域的開始地址和長度。這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，WdfIoTargetFormatRequestForInternalIoctlOthers 會傳回STATUS_SUCCESS。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INVALID_DEVICE_REQUEST	傳輸長度大於緩衝區長度，或 I/O 要求已排入佇列至 I/O 目標。
STATUS_INSUFFICIENT_RESOURCES	架構無法配置系統資源 (通常是記憶體) 。
STATUS_REQUEST_NOT_ACCEPTED	Request 參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程序轉送要求。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

使用 WdfIoTargetFormatRequestForInternalIoctlOthers 方法，後面接著 WdfRequestSend 方法，以同步或異步方式傳送非標準內部裝置控制要求。或者，使用 WdfIoTargetSendInternalIoctlOthersSynchronously 方法來同步傳送非標準內部裝置控制要求。

您可以轉送驅動程式在 I/O 佇列中收到的非標準內部設備控制要求，或者您可以建立並傳送新的要求。不論是哪一種情況，架構都需要要求物件和一些緩衝區空間。

若要轉送您的驅動程式在 I/O 佇列中收到的非標準內部設備控制要求：

針對 WdfIoTargetFormatRequestForInternalIoctlOthers 方法的要求參數指定收到的要求句柄。
針對 WdfIoTargetFormatRequestForInternalIoctlOthers 方法的 OtherArg1、OtherArg2、OtherArg4 參數使用收到的要求內容資訊。
若要取得這些參數值，驅動程式必須呼叫 WdfRequestGetParameters，並使用傳回之WDF_REQUEST_PARAMETERS結構的 DeviceIoControl 成員。

如需轉送 I/O 要求的詳細資訊，請參閱轉送 I/O 要求。

驅動程式通常會將接收的 I/O 要求分成較小的要求，這些要求會傳送至 I/O 目標，因此您的驅動程式可能會建立新的要求。

若要建立新的 I/O 要求：

建立新的要求物件，並提供其 WdfIoTargetFormatRequestForInternalIoctlOthers 方法 的 Request 參數句柄。
呼叫 WdfRequestCreate 以預先配置一或多個要求物件。您可以藉由呼叫 WdfRequestReuse 來重複使用這些要求物件。驅動程式的 EvtDriverDeviceAdd 回呼函式可以預先配置裝置的要求物件。
如果要求需要這些緩衝區，請提供內容緩衝區，並提供 WdfIoTargetFormatRequestForInternalIoctlOthers 方法的 OtherArg1、OtherArg2 和OtherArg4 參數的緩衝區句柄。
您的驅動程式必須將此緩衝區空間指定為WDFMEMORY句柄給架構管理的記憶體。若要取得 WDFMEMORY 句柄，驅動程式會呼叫 WdfMemoryCreate 或 WdfMemoryCreatePreallocated。

在驅動程式呼叫 WdfIoTargetFormatRequestForInternalIoctlOthers 來格式化裝置控制要求之後，驅動程式必須呼叫 WdfRequestSend 以同步或異步方式) 將要求傳送至 I/O 目標 (。

對使用相同要求 之 WdfIoTargetFormatRequestForInternalIoctlOthers 的多個呼叫並不會造成額外的資源配置。因此，為了降低 WdfRequestCreate 將傳回STATUS_INSUFFICIENT_RESOURCES的機會，驅動程式的 EvtDriverDeviceAdd 回呼函式可以呼叫 WdfRequestCreate 來預先配置裝置的一或多個要求物件。驅動程式後續可以重複使用 (呼叫 WdfRequestReuse) 、重新格式化 (呼叫 WdfIoTargetFormatRequestForInternalIoctlOthers) ，然後重新傳送 (呼叫 WdfRequestSend) 每個要求物件，而不會有從稍後呼叫 WdfRequestCreate 傳回值 STATUS_INSUFFICIENT_RESOURCES的風險。 (如果驅動程式每次都未呼叫相同的要求格式方法，則可能會配置其他資源。) 如果參數值未變更，則會傳回對 WdfIoTargetFormatRequestForInternalIoctlOthers 的所有後續 WdfIoTargetFormatRequestForInternalIoctlOthers 呼叫。如果參數值未變更，則會傳回STATUS_SUCCESS。

如需在 I/O 要求完成之後取得狀態資訊的相關信息，請參閱取得完成資訊。

如需 WdfIoTargetFormatRequestForInternalIoctlOthers 的詳細資訊，請參閱將 I/O 要求傳送至一般 I/O 目標。

如需 I/O 目標的詳細資訊，請參閱使用 I/O 目標。

範例

下列程式代碼範例會建立架構記憶體物件、取得記憶體物件所包含的緩衝區，以及初始化緩衝區。然後，此範例會格式化要求、設定 CompletionRoutine 回呼函式，並將要求傳送至 I/O 目標。

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL
                                                        );

if (!NT_SUCCESS(status)) {
    goto Done;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               MyRequestCompletion,
                               NULL
                               );

if (WdfRequestSend(
                   Request,
                   IoTarget,
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
}
else {
    status = STATUS_SUCCESS;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfiotarget.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， RequestFormattedValid (kmdf) 、 RequestSendAndForgetNoFormatting (kmdf) 、 RequestSendAndForgetNoFormatting2 (kmdf)