Expand Minimize

KsCreatePin function

The KsCreatePin function passes a connection request to a device, creating a pin instance. This function can only be called at PASSIVE_LEVEL for kernel-mode clients.

Syntax


NTSTATUS KsCreatePin(
  _In_   HANDLE FilterHandle,
  _In_   PKSPIN_CONNECT Connect,
  _In_   ACCESS_MASK DesiredAccess,
  _Out_  PHANDLE ConnectionHandle
);

Parameters

FilterHandle [in]

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

Connect [in]

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.

DesiredAccess [in]

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.

ConnectionHandle [out]

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

The KsCreatePin function returns STATUS_SUCCESS if the connection was successful, or it returns an error if the connection failed. Additionally, this Win32 error code (from Winerror.h) can be returned:

ERROR_NO_MATCH

1169L (0x491)

The connection failed because the interface, medium, or data format were not found.

Note  Do not rely on using the NT_SUCCESS macro to check return codes from this function: the macro could evaluate to TRUE even though the function returns the ERROR_NO_MATCH error code.

Remarks

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, KsCreatePin creates a pin the caller can use to send requests to the streaming driver specified in Connect->FilterHandle. Connect->PinId determines the pin type of the pin to be created.

Requirements

Header

Ks.h (include Ks.h)

See also

IRP_MJ_CREATE
KSDATAFORMAT
KSPIN_CONNECT

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft