RPC_CALL_ATTRIBUTES_V1_A 構造体 (rpcasync.h)

RPC_CALL_ATTRIBUTES_V1構造体は、RpcServerInqCallAttributes 関数にパラメーターを提供します。 Windows XP および Windows Server 2003 オペレーティング システムの ANSI および UNICODE バージョンで実装されます。

構文

typedef struct tagRPC_CALL_ATTRIBUTES_V1_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;
} RPC_CALL_ATTRIBUTES_V1_A;

メンバー

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 セッションを使用するかどうかを指定します。 0 は、呼び出しが 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 関数が再度呼び出されます。

例

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);

要件

こちらもご覧ください

認証レベルの定数

RpcServerInqCallAttributes