CM_Add_Empty_Log_Conf 函数 (cfgmgr32.h)

项目
08/22/2023

CM_Add_Empty_Log_Conf 函数在本地计算机上为指定的配置类型和指定的设备实例创建空的逻辑配置。

语法

CMAPI CONFIGRET CM_Add_Empty_Log_Conf(
  [out] PLOG_CONF plcLogConf,
  [in]  DEVINST   dnDevInst,
  [in]  PRIORITY  Priority,
  [in]  ULONG     ulFlags
);

参数

[out] plcLogConf

接收空逻辑配置的句柄的位置的地址。

[in] dnDevInst

绑定到本地计算机的调用方提供的设备实例句柄。

[in] Priority

调用方提供的配置优先级值。这必须是下表中列出的常量值之一。常量按优先级顺序列出，从高到低。 (对于具有相同 ulFlags 值的多个配置，系统将尝试使用优先级最高的配置 first.)

优先级常量	定义
LCPRI_FORCECONFIG	强制配置的结果。
LCPRI_BOOTCONFIG	启动配置的结果。
LCPRI_DESIRED	首选配置 (更好的性能) 。
LCPRI_NORMAL	可行的配置 (可接受的性能) 。
LCPRI_LASTBESTCONFIG	仅限内部使用。
LCPRI_SUBOPTIMAL	不是理想的配置，但它可以正常工作。
LCPRI_LASTSOFTCONFIG	仅限内部使用。
LCPRI_RESTART	必须重启系统
LCPRI_REBOOT	系统必须重启 (与LCPRI_RESTART) 相同。
LCPRI_POWEROFF	系统必须关闭并关闭电源。
LCPRI_HARDRECONFIG	必须更改跳线。
LCPRI_HARDWIRED	无法更改配置。
LCPRI_IMPOSSIBLE	配置不能存在。
LCPRI_DISABLED	已禁用配置。

[in] ulFlags

调用方提供的标志，用于指定逻辑配置的类型。必须指定以下标志之一。

配置类型标志	定义
BASIC_LOG_CONF	添加到此配置中的资源描述符将描述基本配置。
FILTERED_LOG_CONF	请勿使用。 (只有 PnP 管理器才能创建筛选的配置。)
ALLOC_LOG_CONF	请勿使用。 (只有 PnP 管理器才能创建分配的配置。)
BOOT_LOG_CONF	添加到此配置中的资源描述符将描述启动配置。
FORCED_LOG_CONF	添加到此配置的资源描述符将描述强制配置。
OVERRIDE_LOG_CONF	添加到此配置中的资源描述符将描述替代配置。

以下位标志之一可以是具有配置类型标志的 ORed。

优先级比较标志	定义
PRIORITY_EQUAL_FIRST	如果相同类型的多个配置 (ulFlags) 具有相同优先级 (Priority) ，则此配置将放在列表的顶部。
PRIORITY_EQUAL_LAST	(默认) 如果相同类型的多个配置 (ulFlags) 具有相同优先级 (优先级) ，则此配置将放置在列表的末尾。

返回值

如果操作成功，函数将返回CR_SUCCESS。否则，它将返回 Cfgmgr32.h 中定义的CR_前缀错误代码之一。

注意从 Windows 8 开始，CM_Add_Empty_Log_Conf在 Wow64 方案中使用时返回CR_CALL_NOT_IMPLEMENTED。若要请求有关本地计算机上的硬件资源的信息，必须使用硬件资源 API 实现应用程序的体系结构本机版本。例如：AMD64 系统的 AMD64 应用程序。

注解

调用 CM_Add_Empty_Log_Conf 可能会导致 CM_Get_First_Log_Conf 和 CM_Get_Next_Log_Conf 返回的句柄无效。因此，如果要在调用 CM_Add_Empty_Log_Conf 后获取逻辑配置，代码必须再次调用 CM_Get_First_Log_Conf ，并从第一个配置开始。

若要删除 CM_Add_Empty_Log_Conf 创建的逻辑配置，请调用 CM_Free_Log_Conf。

必须通过调用 CM_Free_Log_Conf_Handle 显式释放 plcLogConf 中收到的句柄。

此函数的调用方必须具有 SeLoadDriverPrivilege。 Microsoft Windows SDK文档中介绍了 (特权。)

有关使用绑定到本地计算机的设备实例句柄的信息，请参阅 CM_Get_Child。

要求

要求	值
最低受支持的客户端	在 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台	桌面
标头	cfgmgr32.h (包括 Cfgmgr32.h)
Library	Cfgmgr32.lib
DLL	Cfgmgr32.dll