RpcNsMgmtHandleSetExpAge-Funktion (rpcnsi.h)

  • Artikel

Die RpcNsMgmtHandleSetExpAge-Funktion legt das Ablaufalter eines Name-Dienst-Handles für lokale Kopien von Name-Dienst-Daten fest.

Hinweis Diese Funktion wird unter Windows Vista und höheren Betriebssystemen nicht unterstützt.
 

Syntax

RPC_STATUS RpcNsMgmtHandleSetExpAge(
  RPC_NS_HANDLE NsHandle,
  unsigned long ExpirationAge
);

Parameter

NsHandle

Name-Dienst-Handle, für das ein Ablaufalter festgelegt ist. Ein Name-Dienst-Handle wird von einem Namensdienst-Startvorgang zurückgegeben.

ExpirationAge

Ganzzahliger Wert in Sekunden, der das Ablaufalter der lokalen Name-Dienst-Daten festlegt, die von allen nächsten Routinen mithilfe des angegebenen NsHandle-Parameters gelesen werden.

Ein Ablaufalter von 0 bewirkt eine sofortige Aktualisierung der lokalen Name-Dienst-Daten.

Rückgabewert

Wert Bedeutung
RPC_S_OK
 Der Aufruf war erfolgreich.
RPC_S_NAME_SERVICE_UNAVAILABLE
 Der Namensdienst ist nicht verfügbar.
 
Hinweis Eine Liste der gültigen Fehlercodes finden Sie unter RPC-Rückgabewerte.
 

Hinweise

Die RpcNsMgmtHandleSetExpAge-Funktion legt ein Handle-Ablaufalter für ein angegebenes Name-Dienst-Handle (NsHandle) fest. Das Ablaufalter ist die Zeitspanne, die eine lokale Kopie von Daten aus einem name-service-Attribut vorhanden sein kann, bevor eine Anforderung der Anwendung für das Attribut eine Aktualisierung der lokalen Kopie erfordert. Wenn eine Anwendung mit der Ausführung beginnt, gibt die RPC-Laufzeitbibliothek ein Standardablaufalter von zwei Stunden an. Der Standardwert ist global für die Anwendung. Ein Handle-Ablaufalter gilt nur für ein bestimmtes Name-Dienst-Handle und überschreibt vorübergehend das aktuelle globale Ablaufalter.

Ein Handle-Ablaufalter wird ausschließlich von Zeigervorgängen (die Daten aus Name-Dienst-Attributen lesen) verwendet. Ein nächster Vorgang beginnt in der Regel mit der Suche nach einer lokalen Kopie der Attributdaten, die von einer Anwendung angefordert werden. Wenn keine lokale Kopie vorhanden ist, wird beim nächsten Vorgang eine mit neuen Attributdaten aus der name-service-Datenbank erstellt. Wenn bereits eine lokale Kopie vorhanden ist, vergleicht der Vorgang sein tatsächliches Alter mit dem Ablaufalter, das von der Anwendung verwendet wird (in diesem Fall das für das Name-Dienst-Handle festgelegte Ablaufalter). Wenn das tatsächliche Alter das Handle-Ablaufalter überschreitet, versucht der Vorgang automatisch, die lokale Kopie mit neuen Attributdaten zu aktualisieren. Wenn die Aktualisierung nicht möglich ist, bleiben die alten lokalen Daten vorhanden, und der nächste Vorgang schlägt fehl, wodurch der RPC_S_NAME_SERVICE_UNAVAILABLE status Code zurückgegeben wird.

Der Bereich eines Handle-Ablaufalters ist eine einzelne Reihe von nächsten Vorgängen. Die RpcNsMgmtHandleSetExpAge-Funktion wird im folgenden Kontext ausgeführt:

  • Ein Startvorgang erstellt ein Name-Dienst-Handle.
  • Ein Aufruf der RpcNsMgmtHandleSetExpAge-Funktion erstellt ein Ablaufalter für das Handle.
  • Eine Reihe von nächsten Vorgängen für das Name-Dienst-Handle verwendet das Ablaufalter des Handles.
  • Ein abgeschlossener Vorgang für das Name-Dienst-Handle löscht sowohl das Handle als auch sein Ablaufalter.
Hinweis In der Regel sollten Sie rpcNsMgmtHandleSetExpAge vermeiden. Stattdessen sollten Sie sich auf das globale Ablaufalter der Anwendung verlassen. Das Festlegen des Handle-Ablaufalters auf einen kleinen Wert führt dazu, dass die nächsten Vorgänge des Namensdiensts häufig lokale Daten für ein beliebiges name-service-Attribut aktualisieren, das von Ihrer Anwendung angefordert wird. Wenn Sie beispielsweise das Ablaufalter auf 0 festlegen, wird der nächste Vorgang dazu gezwungen, die lokalen Daten für das von Ihrer Anwendung angeforderte Attribut name-service zu aktualisieren. Daher kann das Festlegen eines kleinen Handle-Ablaufalters Zu Leistungsproblemen für Ihre Anwendung führen. Außerdem kann sich ein geringes Ablaufalter negativ auf die Netzwerkleistung aller Anwendungen auswirken, wenn Ihre Anwendung einen Remotename-Dienst-Server verwendet.
 
Beschränken Sie die Verwendung von RpcNsMgmtHandleSetExpAge auf die folgenden Situationen:
  • Wenn Sie immer genaue Name-Dienst-Daten abrufen müssen.

    Beispielsweise müssen Sie bei Verwaltungsvorgängen zum Aktualisieren eines Profils immer den aktuellen Inhalt des Profils anzeigen. In diesem Fall sollte Ihre Anwendung die RpcNsMgmtHandleSetExpAge-Funktion aufrufen und 0 für den ExpirationAge-Parameter angeben, bevor Sie mit der Abfrage nach einem Profil beginnen.

  • Wenn bei einer Anforderung, die das Standardablaufalter verwendet, ein Fehler aufgetreten ist, und Ihre Anwendung den Vorgang wiederholen muss.

    Beispielsweise sollte eine Clientanwendung, die Importvorgänge für den Namensdienst verwendet, zuerst versuchen, Bindungen unter Verwendung des Standardablaufalters der Anwendung abzurufen. Manchmal gibt der Import-Next-Vorgang jedoch entweder keine Bindungshandles oder eine unzureichende Anzahl von diesen zurück. In diesem Fall könnte der Client den Importvorgang wiederholen und nach dem RpcNsBindingImportBegin-Aufruf einen RpcNsMgmtHandleSetExpAge-Aufruf einschließen und 0 für den ExpirationAge-Parameter angeben. Wenn der Client die Import-Next-Funktion erneut aufruft, führt das kleine Handle-Ablaufalter dazu, dass der Import-Next-Vorgang die lokalen Attributdaten aktualisiert.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile rpcnsi.h (include Rpc.h)
Bibliothek Rpcns4.lib
DLL Rpcns4.dll

Weitere Informationen

RpcNsBindingImportBegin

RpcNsMgmtInqExpAge

RpcNsMgmtSetExpAge