UcmConnectorCreate 函式 (ucmmanager.h)

建立連接器物件。

語法

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

參數

[in] WdfDevice

用戶端驅動程式在先前呼叫 WdfDeviceCreate 中所收到的架構裝置物件的句柄。

[in] Config

呼叫端所提供 之UCM_CONNECTOR_CONFIG 結構的指標，該結構是藉由呼叫 UCM_CONNECTOR_CONFIG_INIT 初始化。

[in] Attributes

呼叫端提供的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新連接器對象的屬性。 這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] Connector

接收新連接器物件句柄之位置的指標。

傳回值

如果作業成功，UcmConnectorCreate 會傳回STATUS_SUCCESS。 否則，這個方法可以傳回適當的 NTSTATUS 值。

備註

如果客戶端驅動程式指定已在使用的連接器標識碼，方法會失敗，並出現錯誤碼STATUS_INVALID_PARAMETER。

如果 Type-C 連接器指定為 Dual-Role 埠 (DRP) ，則用戶端驅動程式必須註冊其 EVT_UCM_CONNECTOR_SET_DATA_ROLE 事件回呼。

父物件為 WdfDevice。 您可以將 WDF_OBJECT_ATTRIBUTES 的 ParentObject 成員設定為 NULL 或 WDFDEVICE 句柄。 當父 WDFDEVICE 物件被刪除時，連接器物件會被刪除。

UCM 用戶端驅動程式呼叫 UcmConnectorCreate 的適當位置位於 EvtDevicePrepareHardware 或 EvtDeviceD0Entry 中。 相反地，驅動程式應該在 EvtDeviceReleaseHardware 或 EvtDeviceD0Exit 中釋放 UCMCONNECTOR 句柄。

範例

此範例程式代碼示範如何建立支援 PD 的 Type-C 連接器。

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

規格需求

需求	值
最低支援的用戶端	Windows 10
最低支援的伺服器	Windows Server 2016
目標平台	Windows
最低 KMDF 版本	1.15
最低UMDF版本	2.15
標頭	ucmmanager.h (包含 Ucmcx.h)
程式庫	UcmCxstub.lib
IRQL	PASSIVE_LEVEL

另請參閱

UCM_CONNECTOR_CONFIG

UCM_CONNECTOR_CONFIG_INIT