UcmConnectorCreate function (ucmmanager.h)

Article
10/21/2021

Creates a connector object.

Syntax

NTSTATUS UcmConnectorCreate(
  [in]  WDFDEVICE              WdfDevice,
  [in]  PUCM_CONNECTOR_CONFIG  Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] UCMCONNECTOR           *Connector
);

Parameters

[in] WdfDevice

A handle to a framework device object that the client driver received in the previous call to WdfDeviceCreate.

[in] Config

A pointer to a caller-supplied UCM_CONNECTOR_CONFIG structure that is initialized by calling UCM_CONNECTOR_CONFIG_INIT.

[in] Attributes

A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new connector object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] Connector

A pointer to a location that receives a handle to the new connector object.

Return value

UcmConnectorCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return an appropriate NTSTATUS value.

Remarks

If the client driver specifies a connector identifier that is already in use, the method fails with STATUS_INVALID_PARAMETER error code.

If the Type-C connector is specified to be a Dual-Role port (DRP), the client driver must register its EVT_UCM_CONNECTOR_SET_DATA_ROLE event callback.

The parent object is WdfDevice. You can set the ParentObject member of WDF_OBJECT_ATTRIBUTES to NULL or the WDFDEVICE handle. The connector object gets deleted when the parent WDFDEVICE object gets deleted.

An appropriate place for a UCM client driver to call UcmConnectorCreate is in EvtDevicePrepareHardware or EvtDeviceD0Entry. Conversely, the driver should release the UCMCONNECTOR handle in EvtDeviceReleaseHardware or EvtDeviceD0Exit.

Examples

This example code shows how to create a Type-C connector that is PD-capable.

    
    UCMCONNECTOR Connector;
  
    UCM_CONNECTOR_CONFIG_INIT(&connCfg, 0);

    UCM_CONNECTOR_TYPE_C_CONFIG_INIT(
        &connCfg.TypeCConfig,
        UcmTypeCOperatingModeDrp,
        UcmTypeCCurrentDefaultUsb | UcmTypeCCurrent1500mA | UcmTypeCCurrent3000mA);

    connCfg.EvtSetDataRole = EvtSetDataRole;

    UCM_CONNECTOR_PD_CONFIG_INIT(&connCfg.PdConfig, UcmPowerRoleSink | UcmPowerRoleSource);

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attr, CONNECTOR_CONTEXT);

    status = UcmConnectorCreate(Device, &connCfg, &attr, &Connector);
    if (!NT_SUCCESS(status))
    {
        TRACE_ERROR(
            "UcmConnectorCreate failed with %!STATUS!.",
            status);
        goto Exit;
    }

    TRACE_INFO("UcmConnectorCreate() succeeded.");

Requirements

Requirement	Value
Minimum supported client	Windows 10
Minimum supported server	Windows Server 2016
Target Platform	Windows
Minimum KMDF version	1.15
Minimum UMDF version	2.15
Header	ucmmanager.h (include Ucmcx.h)
Library	UcmCxstub.lib
IRQL	PASSIVE_LEVEL