RPC_CALL_ATTRIBUTES_V2_A structure (rpcasync.h)

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_A {
  unsigned int              Version;
  unsigned long             Flags;
  unsigned long             ServerPrincipalNameBufferLength;
  unsigned char             *ServerPrincipalName;
  unsigned long             ClientPrincipalNameBufferLength;
  unsigned char             *ClientPrincipalName;
  unsigned long             AuthenticationLevel;
  unsigned long             AuthenticationService;
  BOOL                      NullSession;
  BOOL                      KernelModeCaller;
  unsigned long             ProtocolSequence;
  unsigned long             IsClientLocal;
  HANDLE                    ClientPID;
  unsigned long             CallStatus;
  RpcCallType               CallType;
  RPC_CALL_LOCAL_ADDRESS_V1 *CallLocalAddress;
  unsigned short            OpNum;
  UUID                      InterfaceUuid;
} RPC_CALL_ATTRIBUTES_V2_A;

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 RpcServerInqCallAttributes to which this structure was passed.

Value Meaning
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.

KernelModeCaller

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.

Value Meaning
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

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Header rpcasync.h (include Rpc.h)

See also

RpcServerInqCallAttributes