RpcNsMgmtHandleSetExpAge 関数 (rpcnsi.h)

  • [アーティクル]

RpcNsMgmtHandleSetExpAge 関数は、ネーム サービス データのローカル コピーの名前サービス ハンドルの有効期限を設定します。

メモ この関数は、Windows Vista 以降のオペレーティング システムではサポートされていません。
 

構文

RPC_STATUS RpcNsMgmtHandleSetExpAge(
  RPC_NS_HANDLE NsHandle,
  unsigned long ExpirationAge
);

パラメーター

NsHandle

有効期限が設定されている名前サービス ハンドル。 ネーム サービスの開始操作から名前サービス ハンドルが返されます。

ExpirationAge

指定された NsHandle パラメーターを使用して、次のすべてのルーチンによって読み取られたローカルネームサービスデータの有効期限を秒単位で設定する整数値。

有効期限が 0 の場合、ローカルのネーム サービス データが直ちに更新されます。

戻り値

値 説明
RPC_S_OK
 呼び出しは成功しました。
RPC_S_NAME_SERVICE_UNAVAILABLE
 名前サービスを利用できません。
 
メモ 有効なエラー コードの一覧については、「 RPC 戻り値」を参照してください。
 

解説

RpcNsMgmtHandleSetExpAge 関数は、指定された名前サービス ハンドル (NsHandle) のハンドルの有効期限を設定します。 有効期限は、name-service 属性のデータのローカル コピーが存在し、その属性に対するアプリケーションからの要求でローカル コピーの更新が必要になるまでの時間です。 アプリケーションの実行が開始されると、RPC ランタイム ライブラリは既定の有効期限を 2 時間に指定します。 既定値は、アプリケーションに対するグローバルです。 ハンドルの有効期限の有効期間は、特定の名前サービス ハンドルにのみ適用され、現在のグローバル有効期限の有効期間を一時的にオーバーライドします。

ハンドル有効期限の有効期間は、ポインターの次の操作 (名前サービス属性からデータを読み取る) によって排他的に使用されます。 次の操作は、通常、アプリケーションによって要求される属性データのローカル コピーを検索することから始まります。 ローカル コピーがない場合、次の操作では、name-service データベースからの新しい属性データを含むコピーが作成されます。 ローカル コピーが既に存在する場合、操作は実際の有効期間と、アプリケーションで使用されている有効期限 (この場合は、名前サービス ハンドルの有効期限の設定) を比較します。 実際の有効期間がハンドルの有効期限を超えた場合、操作は自動的に新しい属性データを使用してローカル コピーの更新を試みます。 更新が不可能な場合、古いローカル データはそのまま残り、次の操作は失敗し、RPC_S_NAME_SERVICE_UNAVAILABLE状態コードが返されます。

ハンドル有効期限の有効期間のスコープは、次の一連の操作の 1 つのシリーズです。 RpcNsMgmtHandleSetExpAge 関数は、次のコンテキスト内で動作します。

  • 開始操作によって、名前サービス ハンドルが作成されます。
  • RpcNsMgmtHandleSetExpAge 関数を呼び出すと、ハンドルの有効期限が作成されます。
  • 名前サービス ハンドルの一連の次の操作では、ハンドルの有効期限が使用されます。
  • 名前サービス ハンドルに対して実行された操作により、ハンドルとその有効期限の両方が削除されます。
メモ 通常、 RpcNsMgmtHandleSetExpAge の使用は避ける必要があります。 代わりに、アプリケーションのグローバル有効期限に依存する必要があります。 ハンドルの有効期限の有効期間を小さい値に設定すると、名前サービスの次の操作では、アプリケーションによって要求されたすべての name-service 属性のローカル データが頻繁に更新されます。 たとえば、有効期限を 0 に設定すると、アプリケーションによって要求された name-service 属性のローカル データが次の操作で強制的に更新されます。 そのため、ハンドルの有効期限を小さく設定すると、アプリケーションのパフォーマンスの問題が発生する可能性があります。 さらに、アプリケーションでリモート ネーム サービス サーバーを使用している場合、有効期限が小さいと、すべてのアプリケーションのネットワーク パフォーマンスに悪影響を及ぼす可能性があります。
 
RpcNsMgmtHandleSetExpAge の使用を次の状況に制限します。
  • 常に正確なネーム サービス データを取得する必要がある場合。

    たとえば、プロファイルを更新するための管理操作中に、常にプロファイルの現在のコンテンツを確認する必要がある場合があります。 この場合、プロファイルに関する問い合わせを開始する前に、アプリケーションで RpcNsMgmtHandleSetExpAge 関数を呼び出し、 ExpirationAge パラメーターに 0 を指定する必要があります。

  • 既定の有効期限を使用する要求が失敗し、アプリケーションで操作を再試行する必要がある場合。

    たとえば、ネーム サービスのインポート操作を使用するクライアント アプリケーションでは、まず、アプリケーションの既定の有効期限を使用してバインディングを取得する必要があります。 ただし、次のインポート操作では、バインド ハンドルがないか、それらの数が不足している場合があります。 この場合、クライアントはインポート操作を再試行できます。 RpcNsBindingImportBegin 呼び出しの後に、 RpcNsMgmtHandleSetExpAge 呼び出しを含め、 ExpirationAge パラメーターに 0 を指定します。 クライアントが import-next 関数をもう一度呼び出すと、ハンドルの有効期限が小さいと、import-next 操作によってローカル属性データが更新されます。

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー rpcnsi.h (Rpc.h を含む)
Library Rpcns4.lib
[DLL] Rpcns4.dll

関連項目

RpcNsBindingImportBegin

RpcNsMgmtInqExpAge

RpcNsMgmtSetExpAge