KsSynchronousDeviceControl 函式 (ksproxy.h)

發行項
02/29/2024

KsSynchronousDeviceControl 函式會向檔案句柄指定的 KS 對象發出同步裝置 I/O 控制作業。

語法

KSDDKAPI HRESULT KsSynchronousDeviceControl(
  [in]            HANDLE Handle,
  [in]            ULONG  IoControl,
  [in, optional]  PVOID  InBuffer,
  [in]            ULONG  InLength,
  [out, optional] PVOID  OutBuffer,
  [in]            ULONG  OutLength,
  [in, out]       PULONG BytesReturned
);

參數

[in] Handle

要在其中執行作業的 KS 物件句柄。

[in] IoControl

控制程式代碼，識別要對 KS 物件執行的特定作業類型。

[in, optional] InBuffer

緩衝區的指標，其中包含指定要執行之作業的數據。

[in] InLength

InBuffer 緩衝區的大小，以位元組為單位。

[out, optional] OutBuffer

緩衝區的指標，其中包含作業的數據，或接收作業數據的緩衝區空間。

[in] OutLength

OutBuffer 緩衝區的大小，以位元組為單位。

[in, out] BytesReturned

接收 KsSynchronousDeviceControl 儲存在 OutBuffer 緩衝區中之數據大小位元組的變數指標。

傳回值

如果成功，則傳回 NOERROR;否則，會傳回錯誤碼。

備註

若要擷取 KS 物件的句柄，應用程式應該呼叫 IKsObject：：KsGetObjectHandle 方法。

應用程式可以在IoControl中設定控制項程式代碼，以及InBuffer和 OutBuffer 上的緩衝區，如下所示來指定要執行的作業：

將 IoControl 設定為 IOCTL_KS_PROPERTY 以存取屬性。將 InBuffer 設定為指向 KSPROPERTY 結構，這個結構會指定要存取的屬性集屬性，以及是否要擷取屬性的相關信息或設定屬性中的資訊。若要在屬性中設定資訊，請將 OutBuffer 設定為指向該資訊。若要從屬性擷取資訊，請將 OutBuffer 設定為接收該資訊。
將 IoControl 設定為 IOCTL_KS_METHOD 以執行方法。將 InBuffer 設定為指向 KSMETHOD 結構，指定要執行之方法的方法，以及是否要讀取和/或寫入與方法相關的數據。若要讀取數據，請將 OutBuffer 設定為指向該數據。若要寫入數據，請將 OutBuffer 設定為接收該數據。
將 IoControl 設定為 IOCTL_KS_ENABLE_EVENT ，以要求 Handle 指定的 KS 物件會在發生特定事件動作時通知應用程式。將 InBuffer 設定為指向 KSEVENT 結構，以指定要通知的事件集事件。將 OutBuffer 設定為指向 KSEVENTDATA 結構，描述 KS 物件在事件發生時應如何通知應用程式。另請參閱 KS 事件。
將 IoControl 設定為 IOCTL_KS_DISABLE_EVENT ，以通知 Handle 所指定的 KS 物件，以在發生特定事件動作時停止通知應用程式。將 InBuffer 設定為指向先前用於事件通知要求的 KSEVENTDATA 結構。

若要擷取篩選所支援之所有屬性、事件或方法的清單，應用程式可以將 IoControl 設定為IOCTL_KS_PROPERTY、IOCTL_KS_ENABLE_EVENT或IOCTL_KS_METHOD。針對 InBuffer 指向的 KSPROPERTY、KSEVENT 或 KSMETHOD 結構，將 Set 成員設定為 GUID_NULL，並將 Flags 成員設定為 KSPROPERTY_TYPE_SETSUPPORT。

呼叫 KsSynchronousDeviceControl 之後， OutBuffer 將會包含 Handle 所指定物件所支援的一組 GUID 陣列。