共用方式為

WdfIoTargetSendInternalIoctlOthersSynchronously 函式 （wdfiotarget.h）

  • 發行項

[僅適用於 KMDF]

WdfIoTargetSendInternalIoctlOthersSynchronously 方法會建置非標準的內部裝置控制要求，並將它同步傳送至 I/O 目標。

語法

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

參數

[in] IoTarget

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

[in, optional] Request

架構要求物件的句柄。 這個參數是選擇性的，而且可以 NULL。 如需詳細資訊，請參閱下列一節。

[in] IoctlCode

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

[in, optional] OtherArg1

描述包含內容資訊的記憶體緩衝區之 WDF_MEMORY_DESCRIPTOR 結構的指標。 這個參數是選擇性的，而且可以 NULL。

[in, optional] OtherArg2

描述包含內容資訊的記憶體緩衝區之WDF_MEMORY_DESCRIPTOR結構的指標。 這個參數是選擇性的，而且可以 NULL。

[in, optional] OtherArg4

描述包含內容資訊的記憶體緩衝區之WDF_MEMORY_DESCRIPTOR結構的指標。 這個參數是選擇性的，而且可以 NULL。

[in, optional] RequestOptions

呼叫端配置的 WDF_REQUEST_SEND_OPTIONS 結構的指標，指定要求的選項。 此指標是選擇性的，而且可以 NULL。 如需詳細資訊，請參閱下列一節。

[out, optional] BytesReturned

位置的指標，這個位置會藉由呼叫 WdfRequestCompleteWithInformation，以接收另一個驅動程式在完成要求時提供的資訊（例如已傳輸的位元組數目）。 此指標是選擇性的，而且可以 NULL。

傳回值

如果作業成功，WdfIoTargetSendInternalIoctlOthersSynchronously 內部裝置控制要求完成之後傳回，而傳回值則是要求的完成狀態值。 否則，此方法可能會傳回下列其中一個值：

傳回碼 描述
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INFO_LENGTH_MISMATCH
 RequestOptions 參數指向的 WDF_REQUEST_SEND_OPTIONS 結構大小不正確。
STATUS_INVALID_DEVICE_REQUEST
 要求已排入 I/O 目標佇列。
STATUS_INSUFFICIENT_RESOURCES
 架構無法配置系統資源（通常是記憶體）。
STATUS_IO_TIMEOUT
 驅動程式提供逾時值，且要求未在分配的時間內完成。
STATUS_REQUEST_NOT_ACCEPTED
 Request 參數所代表的 I/O 要求封包（IRP），無法提供足夠的 IO_STACK_LOCATION 結構，讓驅動程式轉送要求。
 

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

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

言論

非標準內部裝置控制要求會使用 IOCTL 程式代碼來識別要執行的作業，但要求不會使用其他內部裝置控制要求使用的標準輸入和輸出緩衝區。 如果您要建立一組互動驅動程式，您可以定義這組驅動程式如何使用要求的自變數：OtherArg1、OtherArg2，以及 OtherArg4。

沒有 稱為 OtherArg3 的參數，因為架構會將這些參數與驅動程式 IO_STACK_LOCATION 結構中 Other.Parameters 等位 Argument 4 的成員與 Argument1、Argument2產生關聯。 該聯集中的 Argument3 成員會從 IoctlCode 參數接收值，因此它不適用於其他驅動程式提供的值。

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

如需內部裝置控制要求的詳細資訊，請參閱使用 I/O 控制代碼 。

WdfIoTargetSendInternalIoctlOthersSynchronously 方法在要求完成之前不會傳回，除非驅動程式在 RequestOptions 參數的 WDF_REQUEST_SEND_OPTIONS 結構中提供逾時值，除非偵測到錯誤。

您可以轉送驅動程式在 I/O 佇列中收到的非標準內部裝置控制要求，也可以建立並傳送新的要求。 不論是哪一種情況，架構都需要要求物件，而且可能需要一些內容空間。

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

  1. 為 WdfIoTargetSendInternalIoctlOthersSynchronously 方法的 Request 參數指定收到的要求句柄。
  2. 針對 WdfIoTargetSendInternalIoctlOthersSynchronously 方法的 OtherArg1、OtherArg2和OtherArg4 参数，使用收到的要求內容資訊。

    若要取得這些參數值，驅動程式必須呼叫 WdfRequestGetParameters，並使用傳回之 WDF_REQUEST_PARAMETERS 結構的 DeviceIoControl 成員。

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

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

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

  1. 為 WdfIoTargetSendInternalIoctlOthersSynchronously NULL 要求句柄提供 方法的 Request 參数，或建立新的要求物件並提供句柄：
    • 如果您提供 NULL 要求句柄，架構會使用內部要求物件。 這項技術很容易使用，但驅動程式無法取消要求。
    • 如果您呼叫 WdfRequestCreate 來建立一或多個要求物件，您可以呼叫 WdfRequestReuse來重複使用這些要求物件。 這項技術可讓您的驅動程式 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。 此外，另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。

    您的驅動程式可以指定非NULLRequestOptions 參數、驅動程式提供非NULL 或 NULLRequest 參數。 例如，您可以使用 RequestOptions 參數來指定逾時值。

  2. 提供 WdfIoTargetSendInternalIoctlOthersSynchronously 方法的 OtherArg1、OtherArg2，以及 OtherArg4 參數，如果要求需要的話。

    您的驅動程式可以將此內容空間指定為本機配置的緩衝區、作為WDFMEMORY句柄，或指定為記憶體描述元清單 （MDL）。 您可以使用哪一種方法最方便。

    下列指定緩衝區空間的技術可供使用：

    • 提供本機緩衝區。

      因為 WdfIoTargetSendInternalIoctlOthersSynchronously 同步處理 I/O 要求，因此驅動程式可以建立呼叫例程本機的要求緩衝區，如下列程式代碼範例所示。

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
    • 提供WDFMEMORY句柄。

      呼叫 WdfMemoryCreate 或 WdfMemoryCreatePreallocated，以取得架構管理的記憶體句柄，如下列程式代碼範例所示。

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
    • 提供 MDL。

      驅動程式可以藉由呼叫 WdfRequestRetrieveInputWdmMdl 和 WdfRequestRetrieveOutputWdmMdl來取得與接收的 I/O 要求相關聯的 MDL。

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

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

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

例子

下列程式代碼範例會初始化 IEEE 1394 IRB 結構、使用 結構的位址來初始化 WDF_MEMORY_DESCRIPTOR 結構，然後呼叫 WdfIoTargetSendInternalIoctlOthersSynchronously。

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

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

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

要求

要求 價值
目標平臺 普遍
最低 KMDF 版本 1.0
標頭 wdfiotarget.h （包括 Wdf.h）
連結庫 Wdf01000.sys （請參閱架構連結庫版本控制。）
IRQL PASSIVE_LEVEL
DDI 合規性規則 DeferredRequestCompleted（kmdf），DriverCreate（kmdf），IoctlReqs（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf）、KmdfIrqlExplicit（kmdf）、ReadReqs（kmdf）、RequestCompleted（kmdf）、RequestCompletedLocal、WriteReqs（kmdf）

另請參閱

EvtDriverDeviceAdd

IO_STACK_LOCATION

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForInternalIoctlOthers

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation

WdfRequestCreate

WdfRequestGetParameters

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend