RpcNsProfileEltInqBeginW 函数 (rpcnsi.h)

  • 项目

RpcNsProfileEltInqBegin 函数创建查询上下文，用于查看配置文件中的元素。

注意 Windows Vista 及更高版本的操作系统不支持此功能。
 

语法

RPC_STATUS RpcNsProfileEltInqBeginW(
  unsigned long ProfileNameSyntax,
  RPC_WSTR      ProfileName,
  unsigned long InquiryType,
  RPC_IF_ID     *IfId,
  unsigned long VersOption,
  unsigned long MemberNameSyntax,
  RPC_WSTR      MemberName,
  RPC_NS_HANDLE *InquiryContext
);

参数

ProfileNameSyntax

ProfileName 的语法。

若要使用注册表值项 HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\DefaultSyntax中指定的语法，请提供值 RPC_C_NS_SYNTAX_DEFAULT。

ProfileName

指向要查看的配置文件名称的指针。

InquiryType

要对配置文件执行的查询类型。 下表列出了有效的查询类型。

查询类型 含义
RPC_C_PROFILE_DEFAULT_ELT
 在配置文件中搜索默认配置文件元素（如果有）。 IfId、VersOption 和 MemberName 参数将被忽略。
RPC_C_PROFILE_ALL_ELTS
 返回配置文件中的每个元素。 IfId、VersOption 和 MemberName 参数将被忽略。
RPC_C_PROFILE_MATCH_BY_IF
 在配置文件中搜索包含 IfId 和 VersOption 指定的接口标识的元素。 将忽略 MemberName 参数。
RPC_C_PROFILE_MATCH_BY_MBR
 在配置文件中搜索包含 MemberName 的元素。 IfId 和 VersOption 参数将被忽略。
RPC_C_PROFILE_MATCH_BY_BOTH
 在配置文件中搜索包含接口标识和由 IfId、 VersOption 和 MemberName 参数标识的成员的元素。

IfId

指向 RpcNsProfileEltInqNext 函数要返回的配置文件元素的接口标识的指针。

仅当为 InquiryType 参数指定值 RPC_C_PROFILE_MATCH_BY_IF 或 RPC_C_PROFILE_MATCH_BY_BOTH 时，才使用 IfId 参数。 否则， IfId 将被忽略，并且可以指定 null 值。

VersOption

指定 RpcNsProfileEltInqNext 函数如何使用 IfId 参数。 仅当为 InquiryType 指定值 RPC_C_PROFILE_MATCH_BY_IF 或 RPC_C_PROFILE_MATCH_BY_BOTH 时，才使用此参数。 否则，将忽略此参数，并且可以指定 0 值。

下表描述了 VersOption 的有效值。

值 含义
RPC_C_VERS_ALL
 返回提供指定接口 UUID 的配置文件元素，而不考虑版本号。 对于此值，请在 IfId 中为主要版本和次要版本指定 0。
RPC_C_VERS_COMPATIBLE
 返回提供指定接口 UUID 的主版本和大于或等于指定接口 UUID 次要版本的次要版本的配置文件元素。
RPC_C_VERS_EXACT
 返回提供指定接口 UUID 的指定版本的配置文件元素。
RPC_C_VERS_MAJOR_ONLY
 返回提供指定接口 UUID 的相同主版本的配置文件元素， (忽略次要版本) 。 对于此值，请在 IfId 中为次要版本指定 0。
RPC_C_VERS_UPTO
 返回提供小于或等于指定主版本和次要版本的指定接口 UUID 版本的配置文件元素。 (例如，如果 IfId 包含 V2.0，配置文件包含具有 V1.3、V2.0 和 V2.1 的元素， 则 RpcNsProfileEltInqNext 函数返回 V1.3 和 V2.0.)

MemberNameSyntax

MemberName 的语法，以及 RpcNsProfileEltInqNext 函数中的返回参数 MemberName。

若要使用注册表值项 HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\DefaultSyntax中指定的语法，请提供值 RPC_C_NS_SYNTAX_DEFAULT。

MemberName

指向 RpcNsProfileEltInqNext 函数在配置文件元素中查找的成员名称的指针。 仅当为 InquiryType 指定值 RPC_C_PROFILE_MATCH_BY_MBR 或 RPC_C_PROFILE_MATCH_BY_BOTH 时，才使用 MemberName 参数。 否则， 将忽略 MemberName ，并且可以指定 null 值。

InquiryContext

返回指向名称服务句柄的指针，以便与 RpcNsProfileEltInqNext 和 RpcNsProfileEltInqDone 函数一起使用。

返回值

值 含义
RPC_S_OK
 调用成功。
RPC_S_INVALID_VERS_OPTION
 版本选项无效。
RPC_S_INVALID_NAME_SYNTAX
 名称语法无效。
RPC_S_UNSUPPORTED_NAME_SYNTAX
 不支持名称语法。
RPC_S_INCOMPLETE_NAME
 名称不完整。
RPC_S_ENTRY_NOT_FOUND
 找不到名称服务条目。
RPC_S_NAME_SERVICE_UNAVAILABLE
 名称服务不可用。
 
注意 有关有效错误代码的列表，请参阅 RPC 返回值。
 

注解

RpcNsProfileEltInqBegin 函数创建查询上下文，用于查看配置文件中的元素。

使用 InquiryType 参数，应用程序指定要从对 RpcNsProfileEltInqNext 的调用返回以下哪些配置文件元素：

  • 默认元素
  • 所有元素
  • 具有指定接口标识的元素
  • 具有指定成员名称的元素
  • 具有指定接口标识和成员名称的元素
在调用 RpcNsProfileEltInqNext 之前，应用程序必须先调用 RpcNsProfileEltInqBegin 来创建查询上下文。

查看完配置文件元素后，应用程序会调用 RpcNsProfileEltInqDone 函数来删除查询上下文。

注意 Windows 2000 Active Directory 支持此函数。 早期版本的 Windows NT 仅支持将此函数与单元格目录服务 (CDS) 配合使用。
 

注意

rpcnsi.h 标头将 RpcNsProfileEltInqBegin 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 rpcnsi.h (包括 Rpc.h)
Library Rpcns4.lib
DLL Rpcns4.dll

另请参阅

RpcIfInqId

RpcNsProfileEltInqDone

RpcNsProfileEltInqNext