RPC_CALL_ATTRIBUTES_V2 structure

The RPC_CALL_ATTRIBUTES_V2 structure provides parameters to the RpcServerInqCallAttributes function. Version 2 specifies support for local addresses and client process IDs.

Syntax


typedef struct tagRPC_CALL_ATTRIBUTES_V2 {
  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;
  BOOL                   KernelMode;
  unsigned long          ProtocolSequence;
  RpcCallClientLocality  IsClientLocal;
  HANDLE                 ClientPID;
  unsigned long          CallStatus;
  RpcCallType            CallType;
  RPC_CALL_LOCAL_ADDRESS *CallLocalAddress;
  unsigned short         OpNum;
  UUID                   InterfaceUuid;
} RPC_CALL_ATTRIBUTES_V2, RPC_CALL_ATTRIBUTES;

Members

Version

Version of the RPC_CALL_ATTRIBUTES structure. For this structure, this value must be set to 2.

Flags

Bitmasked flags that indicate which members of this structure should be populated by the call to RpcServerInqCallAttributesto which this structure was passed.

ValueMeaning
RPC_QUERY_SERVER_PRINCIPAL_NAME

Indicates that RpcServerInqCallAttributes should populate the ServerPrincipalName member of this structure.

RPC_QUERY_CLIENT_PRINCIPAL_NAME

Indicates that RpcServerInqCallAttributes should populate the ClientPrincipalName member of this structure.

RPC_QUERY_CALL_LOCAL_ADDRESS

Indicates that RpcServerInqCallAttributes should populate the CallLocalAddress member of this structure.

RPC_QUERY_CLIENT_PID

Indicates that RpcServerInqCallAttributes should populate the ClientPID member of this structure. This flag is only supported for the ncalrpc protocol sequence.

 

ServerPrincipalNameBufferLength

Length of ServerPrincipalName, in bytes. If insufficient, ServerPrincipalName is unchanged, and ServerPrincipalNameBufferLength indicates the required buffer length including the terminating NULL character, and ERROR_MORE_DATA is returned. If ServerPrincipalNameBufferLength is longer than necessary, upon return it is set to the actual length used, in bytes, including the terminating NULL character. See Remarks.

If the protocol sequence does not support retrieving a server principal name, ServerPrincipalNameBufferLength is set to zero on return, and the buffer pointed by ServerPrincipalName is unmodified.

Windows XP:  Only the ncacn_* group of protocol sequences support retrieving the server principal name.

If the RPC_QUERY_SERVER_PRINCIPAL_NAME flag is not specified, ServerPrincipalNameBufferLength is ignored. If ServerPrincipalNameBufferLength is nonzero and ServerPrincipalName is NULL, ERROR_INVALID_PARAMETER is returned.

ServerPrincipalName

Pointer to the server principal name, if requested in Flags and supported by the protocol sequence. Upon any return value other than RPC_S_OK or ERROR_MORE_DATA, the content of ServerPrincipalName is undefined and may have been modified by RPC.

ClientPrincipalNameBufferLength

Length of the buffer pointed to by ClientPrincipalName, in bytes. If insufficient, ClientPrincipalName is unchanged, and ClientPrincipalNameBufferLength indicates the required buffer length including the terminating NULL character, and ERROR_MORE_DATA is returned. If ClientPrincipalNameBufferLength is longer than necessary, upon return it is set to the actual length used, in bytes, including the terminating NULL character.

If the protocol sequence does not support retrieving a client principal name, ClientPrincipalNameBufferLength is set to zero on return, and the buffer pointed by ClientPrincipalName is unmodified.

Windows XP:  Only the ncalrpc protocol sequence supports retrieving the client principal name.

If the RPC_QUERY_CLIENT_PRINCIPAL_NAME flag is not specified, ClientPrincipalNameBufferLength is ignored. If ClientPrincipalNameBufferLength is nonzero and ClientPrincipalName is NULL, ERROR_INVALID_PARAMETER is returned.

ClientPrincipalName

Pointer to the client principal name, if requested in Flags member and supported by the protocol sequence. Upon any return value other than RPC_S_OK or ERROR_MORE_DATA, the content of ClientPrincipalName is undefined and may have been modified by RPC.

AuthenticationLevel

Authentication level for the call. See Authentication-Level Constants for authentication levels supported by RPC.

AuthenticationService

Authentication service, or security provider, used to make the remote procedure call.

NullSession

Specifies whether a Null session is used. Zero indicates the call is not coming over a Null session; any other value indicates a Null session.

KernelMode

Specifies whether or not the call came from kernel mode. Zero indicates the call is not coming from kernel mode; any other value indicates that it was made from kernel mode.

ProtocolSequence

Constant that indicates the protocol sequence over which the call was made.

IsClientLocal

RpcCallClientLocality enumeration value that indicates the locality of the client (local, remote, or unknown).

ClientPID

Handle that contains the process ID of the calling client. This field is only supported for the ncalrpc protocol sequence, and is populated only when RPC_QUERY_CLIENT_PID is specified in the Flags parameter.

CallStatus

Bit field that specifies the status of the RPC call.

ValueMeaning
RPC_CALL_STATUS_IN_PROGRESS
0x01

The call is in progress.

RPC_CALL_STATUS_CANCELLED
0x02

The call was canceled.

RPC_CALL_STATUS_DISCONNECTED
0x03

The client has disconnected.

 

CallType

RpcCallType enumeration value that indicates the type of the RPC call.

CallLocalAddress

Pointer to a RPC_CALL_LOCAL_ADDRESS structure that contains information to the server about the local address on which the call was made.

This field must not be NULL if RPC_QUERY_CALL_LOCAL_ADDRESS is specified in Flags; otherwise, RPC_S_INVALID_ARG is returned.

If the buffer supplied by the application is insufficient, RpcServerInqCallAttributes returns ERROR_MORE_DATA.

OpNum

The opnum value associated with the call in the corresponding IDL file.

InterfaceUuid

The interface UUID on which the call is made.

Remarks

The RPC_CALL_ATTRIBUTES structure uses a versioning scheme to enable the RpcServerInqCallAttributes function to incorporate new capabilities without having to introduce new functions with suffix identifiers. For example, a second version of the RPC_CALL_ATTRIBUTES, identified with a simple #define in the header, can add new members to facilitate new functionality built into future versions of the RpcServerInqCallAttributes function, without having to release a corresponding alternative function.

The Version member indicates the version of the RPC_CALL_ATTRIBUTES structure (currently either RPC_CALL_ATTRIBUTES_V1 or RPC_CALL_ATTRIBUTES_V2) being used by the calling application. This identification enables the RPC run time to provide backward compatibility for applications not using the most current version of the structure.

Until the process terminates, ClientPID uniquely identifies that process on the client. When the process terminates, the process ID specified by ClientPID can be used by new processes.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Rpcasync.h (include Rpc.h)

Unicode and ANSI names

RPC_CALL_ATTRIBUTES_V2_W (Unicode) and RPC_CALL_ATTRIBUTES_V2_A (ANSI)

See also

RpcServerInqCallAttributes

 

 

Community Additions

ADD
Show:
© 2014 Microsoft