KsSynchronousDeviceControl-Funktion (ksproxy.h)

Artikel
02/07/2025

Die KsSynchronousDeviceControl-Funktion stellt einen synchronen Geräte-E/A-Steuerungsvorgang auf das KS-Objekt aus, das von einem Dateihandle angegeben wird.

Syntax

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
);

Parameter

[in] Handle

Behandeln Sie das KS-Objekt, für das der Vorgang ausgeführt werden soll.

[in] IoControl

Steuerelementcode, der einen bestimmten Vorgangstyp identifiziert, der für ein KS-Objekt ausgeführt werden soll.

[in, optional] InBuffer

Zeigen Sie auf einen Puffer, der Daten enthält, die den auszuführenden Vorgang angeben.

[in] InLength

Größe des Puffers in Bytes bei InBuffer-.

[out, optional] OutBuffer

Zeigen Sie auf einen Puffer, der entweder Daten für den Vorgang oder Pufferraum enthält, der Daten für den Vorgang empfängt.

[in] OutLength

Größe des Puffers in Bytes bei OutBuffer-.

[in, out] BytesReturned

Zeigen Sie auf eine Variable, die die Größe der Daten in Byte empfängt, die KsSynchronousDeviceControl KsSynchronousDeviceControl im Puffer bei OutBuffer-.

Rückgabewert

Gibt NOERROR zurück, wenn dies erfolgreich ist; andernfalls wird ein Fehlercode zurückgegeben.

Bemerkungen

Um das Handle für das KS-Objekt abzurufen, sollte eine Anwendung die IKsObject::KsGetObjectHandle--Methode aufrufen.

Eine Anwendung kann den Steuercode in IoControl- und die Puffer bei InBuffer- festlegen und OutBuffer- wie folgt, um den auszuführenden Vorgang anzugeben:

Legen Sie IoControl- auf IOCTL_KS_PROPERTY fest, um auf eine Eigenschaft zuzugreifen. Legen Sie InBuffer- so fest, dass sie auf eine KSPROPERTY- Struktur zeigt, die die Eigenschaft angibt, auf die zugegriffen werden soll, und ob Informationen zu der Eigenschaft oder zum Festlegen von Informationen in der Eigenschaft abgerufen werden sollen. Um Informationen in der Eigenschaft festzulegen, legen Sie OutBuffer- fest, um auf diese Informationen zu verweisen. Um Informationen aus der Eigenschaft abzurufen, legen Sie OutBuffer- fest, um diese Informationen zu empfangen.
Legen Sie IoControl- auf IOCTL_KS_METHOD fest, um eine Methode auszuführen. Legen Sie InBuffer- so fest, dass sie auf eine KSMETHOD- Struktur verweist, die die auszuführende Methode angibt und ob Daten im Zusammenhang mit der Methode gelesen und/oder geschrieben werden sollen. Um Daten zu lesen, legen Sie OutBuffer- so fest, dass sie auf diese Daten verweisen. Um Daten zu schreiben, legen Sie OutBuffer- fest, um diese Daten zu empfangen.
Legen Sie IoControl- auf IOCTL_KS_ENABLE_EVENT fest, um anzufordern, dass das durch Handle angegebene KS-Objekt die Anwendung benachrichtigen, wenn eine bestimmte Ereignisaktion auftritt. Legen Sie InBuffer- so fest, dass sie auf eine KSEVENT--Struktur verweist, die das Ereignis des Ereignissatzes angibt, über das benachrichtigt werden soll. Legen Sie OutBuffer- so fest, dass sie auf eine KSEVENTDATA- Struktur verweist, die beschreibt, wie das KS-Objekt die Anwendung benachrichtigen soll, wenn das Ereignis auftritt. Siehe auch KS-Ereignisse.
Legen Sie IoControl- auf IOCTL_KS_DISABLE_EVENT fest, um das KS-Objekt zu informieren, das von Handle angegeben wird, um die Benachrichtigung der Anwendung zu beenden, wenn eine bestimmte Ereignisaktion auftritt. Legen Sie InBuffer- so fest, dass sie auf die KSEVENTDATA- Struktur verweist, die zuvor in der Ereignisbenachrichtigungsanforderung verwendet wurde.

Um eine Liste aller Eigenschaften, Ereignisse oder Methoden abzurufen, die von einem Filter unterstützt werden, kann eine Anwendung IoControl- auf IOCTL_KS_PROPERTY, IOCTL_KS_ENABLE_EVENT oder IOCTL_KS_METHOD festlegen. Legen Sie für die KSPROPERTY-, KSEVENT- oder KSMETHOD-Struktur, auf die InBuffer Punkte festgelegt ist, das Element auf GUID_NULL festlegen und das Flags-Element auf KSPROPERTY_TYPE_SETSUPPORT festlegen.

Nach dem Aufruf von KsSynchronousDeviceControlenthält OutBuffer- ein Array von festgelegten GUIDs, die von dem durch Handleangegebenen Objekt unterstützt werden.