RPC_CALL_ATTRIBUTES_V1_W 结构 (rpcasync.h)

  • 项目

RPC_CALL_ATTRIBUTES_V1 结构为 RpcServerInqCallAttributes 函数提供参数。 在适用于 Windows XP 和 Windows Server 2003 操作系统的 ANSI 和 UNICODE 版本中实现。

语法

typedef struct tagRPC_CALL_ATTRIBUTES_V1_W {
  unsigned int   Version;
  unsigned long  Flags;
  unsigned long  ServerPrincipalNameBufferLength;
  unsigned short *ServerPrincipalName;
  unsigned long  ClientPrincipalNameBufferLength;
  unsigned short *ClientPrincipalName;
  unsigned long  AuthenticationLevel;
  unsigned long  AuthenticationService;
  BOOL           NullSession;
} RPC_CALL_ATTRIBUTES_V1_W;

成员

Version

调用应用程序使用的 RpcServerInqCallAttributes 函数的版本。 请参阅“备注”。

Flags

指定用于请求RPC_QUERY_SERVER_PRINCIPAL_NAME或RPC_QUERY_CLIENT_PRINCIPAL_NAME的有效标志的位掩码。 请参阅“备注”。

ServerPrincipalNameBufferLength

ServerPrincipalName 的长度（以字节为单位）。 如果不足， 则 ServerPrincipalName 保持不变， ServerPrincipalNameBufferLength 指示所需的缓冲区长度（包括终止 NULL 字符），并返回ERROR_MORE_DATA。 如果 ServerPrincipalNameBufferLength 超过必要长度，则返回时，它会设置为使用的实际长度（以字节为单位），包括终止 NULL 字符。 请参阅“备注”。

如果协议序列不支持检索服务器主体名称， 则 ServerPrincipalNameBufferLength 在返回时设置为零， ServerPrincipalName 指向的缓冲区未修改。 Windowsxp： 只有 ncacn_* 组协议序列支持检索服务器主体名称。

如果未指定RPC_QUERY_SERVER_PRINCIPAL_NAME标志，则忽略 ServerPrincipalNameBufferLength 。 如果 ServerPrincipalNameBufferLength 为非零值， ServerPrincipalName 为 NULL，则返回ERROR_INVALID_PARAMETER。

ServerPrincipalName

指向服务器主体名称的指针（如果在 标志 中请求，并且受协议序列支持）。 除 RPC_S_OK 或 ERROR_MORE_DATA 以外的任何返回值时， ServerPrincipalName 的内容是未定义且可能已被 RPC 修改。

ClientPrincipalNameBufferLength

ClientPrincipalName 指向的缓冲区的长度（以字节为单位）。 如果不足， 则 ClientPrincipalName 保持不变， ClientPrincipalNameBufferLength 指示所需的缓冲区长度（包括终止 NULL 字符），并返回ERROR_MORE_DATA。 如果 ClientPrincipalNameBufferLength 超过必要长度，则返回时，它会设置为使用的实际长度（以字节为单位），包括终止 NULL 字符。

如果协议序列不支持检索客户端主体名称， 则 ClientPrincipalNameBufferLength 在返回时设置为零，并且 ClientPrincipalName 指向的缓冲区未修改。 Windowsxp： 只有 ncalrpc 协议序列支持检索客户端主体名称。

如果未指定 RPC_QUERY_CLIENT_PRINCIPAL_NAME 标志，则会忽略 ClientPrincipalNameBufferLength 。 如果 ClientPrincipalNameBufferLength 为非零值， ClientPrincipalName 为 NULL，则返回ERROR_INVALID_PARAMETER。

ClientPrincipalName

指向客户端主体名称的指针（如果在 Flags 成员中请求并受协议序列支持）。 在除 RPC_S_OK 或 ERROR_MORE_DATA 以外的任何返回值时， ClientPrincipalName 的内容是未定义且可能已被 RPC 修改。

AuthenticationLevel

呼叫的身份验证级别。 有关 RPC 支持的身份验证级别，请参阅 身份验证级别常量 。

AuthenticationService

身份验证服务或安全提供程序，用于进行远程过程调用。

NullSession

指定是否使用 Null 会话。 零表示调用不是通过 Null 会话进行;任何其他值指示 Null 会话。

注解

RPC_CALL_ATTRIBUTES 结构使用版本控制方案，使 RpcServerInqCallAttributes 函数能够合并新功能，而无需引入具有后缀标识符的新函数。 例如， RPC_CALL_ATTRIBUTES的第二个版本（在标头中用简单 #define 标识）可以添加新成员，以促进内置到 RpcServerInqCallAttributes 函数的未来版本中的新功能，而无需发布相应的替代函数。

Version 成员指示调用应用程序当前RPC_CALL_ATTRIBUTES_V1或RPC_CALL_ATTRIBUTES_V2) (RPC_CALL_ATTRIBUTES结构的版本。 此标识使 RPC 运行时能够为不使用最新版本结构的应用程序提供向后兼容性。

在 Flags 成员中指定RPC_QUERY_SERVER_PRINCIPAL_NAME指示 RpcServerInqCallAttributes 返回 ServerPrincipalName 中的服务器主体名称。 如果未指定 RPC_QUERY_SERVER_PRINCIPAL_NAME，RpcServerInqCallAttributes 不会修改 在 ServerPrincipalName 中传递的指针，也不会在该内存位置中存储任何内容。 在 Flags 成员中指定RPC_QUERY_CLIENT_PRINCIPAL_NAME指示 RpcServerInqCallAttributes 返回 ClientPrincipalName 中的客户端主体名称。 如果未指定 RPC_QUERY_CLIENT_PRINCIPAL_NAME，RpcServerInqCallAttributes 不会修改 在 ClientPrincipalName 中传递的指针，也不会在该内存位置存储任何内容。

检索客户端和服务器主体名称时的最佳处理机制是存储 ClientPrincipalNameBufferLength 和 ServerPrincipalNameBufferLength 的长度，如果返回ERROR_MORE_DATA，请将存储的长度与这些成员中返回的长度进行比较。 存储值小于或等于返回值的成员已成功返回，表示另一个成员的缓冲区不足。 在后续调用中，省略成功返回的主体名称的 标志;这避免了与另一个检索和成功返回的主体名称副本关联的处理。

通常通过两种方式调用 RPC_CALL_ATTRIBUTES_V1 结构：

  • 第一种方法：为第一个 RpcServerInqCallAttributes 函数调用上的 ServerPrincipalNameBufferLength 或 ClientPrincipalNameBufferLength 成员指定零，以检索所需的缓冲区长度，或确定协议是否支持返回主体名称。 检索所需的缓冲区长度后，将分配缓冲区所需的长度，并执行第二次调用以获取缓冲区的实际长度。
  • 第二种方法：调用方从合理的缓冲区开始，通常在堆栈上分配，如果返回ERROR_MORE_DATA，则分配所需长度的缓冲区，并再次调用 RpcServerInqCallAttributes 函数。
在大多数情况下，第二种方法提供最佳性能，因为调用方不需要执行内存分配。

示例

RPC_CALL_ATTRIBUTES CallAttributes;  // this maps to RPC_CALL_ATTRIBUTES_V1

memset(&CallAttributes, 0, sizeof(CallAttributes));
CallAttributes.Version = RPC_CALL_ATTRIBUTES_VERSION;    // maps to 1
CallAttributes.Flags = ;//....
Status = RpcServerInqCallAttributes(0, &CallAttributes);

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
标头 rpcasync.h (包括 Rpc.h)

另请参阅

身份验证级别常量

RpcServerInqCallAttributes