KsCreatePin2 function (ks.h)

Article
02/22/2024

Passes a connection request to a device, creating a pin instance.

Supported starting in Windows 8.

Syntax

KSDDKAPI HRESULT KsCreatePin2(
  [in]  HANDLE         FilterHandle,
  [in]  PKSPIN_CONNECT Connect,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        ConnectionHandle
);

Parameters

[in] FilterHandle

Specifies the handle of the filter initiating the create request and where the connection will occur.

[in] Connect

Pointer to a KSPIN_CONNECT structure that contains parameters for the requested connection. This should be followed in memory by a KSDATAFORMAT data structure, describing the data format requested for the connection.

[in] DesiredAccess

Specifies the access desired to the pin. This is typically GENERIC_READ or GENERIC_WRITE. For data flowing into the pin this value should be set to GENERIC_WRITE, and for data flowing out of the pin this should be set to GENERIC_READ regardless of the communication method.

[out] ConnectionHandle

Specifies the connection handle passed. The routine fills this in with a handle to the file object of the created connection. This value can then be used to disconnect with the CloseHandle function.

Return value

Returns NOERROR if successful; otherwise, returns an error code.

Remarks

This is a new version of the KsCreatePin function and uses the device broker to create the handle to the kernel streaming object. In addition, the Component Object Model (COM) CoInitialize function must be called before this function is called.

The routine sends an IRP_MJ_CREATE request to the driver. The driver accepts the request only if the interface, medium, and data format are compatible.

If Connect->PinToHandle is NULL, KsCreatePin2 creates a pin that the caller can use to send requests to the streaming driver specified in Connect->FilterHandle. Connect->PinId determines the type of pin to be created.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Minimum supported server	Windows Server 2012
Target Platform	Universal
Header	ks.h (include Ks.h)
IRQL	PASSIVE_LEVEL