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 は戻り値として 0 に設定され、 ServerPrincipalName が指すバッファーは変更されません。 Windows XP: サーバー プリンシパル名の取得をサポートするのは、プロトコル シーケンスの ncacn_* グループのみです。

RPC_QUERY_SERVER_PRINCIPAL_NAME フラグが指定されていない場合、 ServerPrincipalNameBufferLength は無視されます。 ServerPrincipalNameBufferLength が 0 以外で、ServerPrincipalName が NULL の場合は、ERROR_INVALID_PARAMETERが返されます。

ServerPrincipalName

Flags で要求され、プロトコル シーケンスでサポートされている場合は、サーバー プリンシパル名へのポインター。 RPC_S_OKまたはERROR_MORE_DATA以外の戻り値の場合、 ServerPrincipalName の内容は未定義であり、RPC によって変更された可能性があります。

ClientPrincipalNameBufferLength

ClientPrincipalName が指すバッファーの長さ (バイト単位)。 不十分な場合、 ClientPrincipalName は変更されず、 ClientPrincipalNameBufferLength は終端 の NULL 文字を含む必要なバッファー長を示し、ERROR_MORE_DATAが返されます。 ClientPrincipalNameBufferLength が必要以上に長い場合は、返されるときに、使用される実際の長さ (終端の NULL 文字を含むバイト単位) に設定されます。

プロトコル シーケンスでクライアント プリンシパル名の取得がサポートされていない場合、 ClientPrincipalNameBufferLength は戻り値として 0 に設定され、 ClientPrincipalName が指すバッファーは変更されません。 Windows XP: ncalrpc プロトコル シーケンスのみがクライアント プリンシパル名の取得をサポートします。

RPC_QUERY_CLIENT_PRINCIPAL_NAME フラグが指定されていない場合、 ClientPrincipalNameBufferLength は無視されます。 ClientPrincipalNameBufferLength が 0 以外で、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 関数がサフィックス識別子を持つ新しい関数を導入することなく、新しい機能を組み込むことができます。 たとえば、ヘッダーの単純な #define で識別される 2 番目のバージョンの RPC_CALL_ATTRIBUTESでは、新しいメンバーを追加して、対応する代替関数を解放することなく、将来のバージョンの RpcServerInqCallAttributes 関数に組み込まれる新しい機能を容易にすることができます。

Version メンバーは、呼び出し元のアプリケーションで使用されているRPC_CALL_ATTRIBUTES構造体 (現在はRPC_CALL_ATTRIBUTES_V1またはRPC_CALL_ATTRIBUTES_V2) のバージョンを示します。 この識別により、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構造体は、通常、次の 2 つの方法で呼び出されます。

  • 最初の方法: 必要なバッファー長を取得するか、プロトコルがプリンシパル名の返しをサポートしているかどうかを判断するために、最初の RpcServerInqCallAttributes 関数呼び出しの ServerPrincipalNameBufferLength メンバーまたは ClientPrincipalNameBufferLength メンバーに 0 を指定します。 必要なバッファー長を取得すると、必要な長さのバッファーが割り当てられ、バッファーの実際の長さを取得するために 2 回目の呼び出しが行われます。
  • 2 番目の方法: 呼び出し元は妥当なバッファーで始まり、多くの場合、スタックに割り当てられ、ERROR_MORE_DATAが返された場合は、必要な長さのバッファーが割り当てられ、 RpcServerInqCallAttributes 関数が再度呼び出されます。
2 番目のメソッドは、呼び出し元がメモリ割り当てを実行する必要がないため、ほとんどの場合に最適なパフォーマンスを提供します。

例

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 (デスクトップ アプリのみ)
Header rpcasync.h (Rpc.h を含む)

こちらもご覧ください

認証レベルの定数

RpcServerInqCallAttributes