Fonction RpcNsMgmtHandleSetExpAge (rpcnsi.h)

La fonction RpcNsMgmtHandleSetExpAge définit l’âge d’expiration d’un handle name-service pour les copies locales des données name-service.

Note Cette fonction n’est pas prise en charge sur Windows Vista et les systèmes d’exploitation ultérieurs.

 

Syntaxe

RPC_STATUS RpcNsMgmtHandleSetExpAge(
  RPC_NS_HANDLE NsHandle,
  unsigned long ExpirationAge
);

Paramètres

NsHandle

Handle de service de nom pour lequel un âge d’expiration est défini. Un handle de service de nom est retourné à partir d’une opération de début du service de noms.

ExpirationAge

Valeur entière, en secondes, qui définit l’âge d’expiration des données de nom-service locales lues par toutes les routines suivantes à l’aide du paramètre NsHandle spécifié.

Un âge d’expiration de 0 entraîne une mise à jour immédiate des données de service de nom local.

Valeur retournée

Valeur	Signification
RPC_S_OK	L’appel a réussi.
RPC_S_NAME_SERVICE_UNAVAILABLE	Nom de service indisponible.

 

Note Pour obtenir la liste des codes d’erreur valides, consultez Valeurs de retour RPC.

 

Notes

La fonction RpcNsMgmtHandleSetExpAge définit un âge d’expiration de handle pour un handle name-service spécifié (NsHandle). L’âge d’expiration est la durée pendant laquelle une copie locale de données à partir d’un attribut name-service peut exister avant qu’une demande de l’application pour l’attribut nécessite la mise à jour de la copie locale. Lorsqu’une application commence à s’exécuter, la bibliothèque d’exécution RPC spécifie une durée d’expiration par défaut de deux heures. La valeur par défaut est globale pour l’application. Un âge d’expiration de handle s’applique uniquement à un handle de nom-service spécifique et remplace temporairement l’âge d’expiration global actuel.

Un âge d’expiration de handle est utilisé exclusivement par les opérations de pointeur suivant (qui lisent les données des attributs name-service). Une opération suivante commence généralement par rechercher une copie locale des données d’attribut demandées par une application. En l’absence d’une copie locale, l’opération suivante en crée une avec de nouvelles données d’attribut à partir de la base de données name-service. Si une copie locale existe déjà, l’opération compare son âge réel à l’âge d’expiration utilisé par l’application (qui, dans ce cas, est l’âge d’expiration défini pour le handle name-service). Si l’âge réel dépasse l’âge d’expiration du handle, l’opération tente automatiquement de mettre à jour la copie locale avec de nouvelles données d’attribut. Si la mise à jour est impossible, les anciennes données locales restent en place et l’opération suivante échoue, renvoyant le code RPC_S_NAME_SERVICE_UNAVAILABLE status.

L’étendue d’un âge d’expiration de handle est une seule série d’opérations suivantes. La fonction RpcNsMgmtHandleSetExpAge fonctionne dans le contexte suivant :

• Une opération de début crée un handle de service de nom.
• Un appel à la fonction RpcNsMgmtHandleSetExpAge crée un âge d’expiration pour le handle.
• Une série d’opérations suivantes pour le handle de nom-service utilise l’âge d’expiration du handle.
• Une opération effectuée pour le handle name-service supprime à la fois le handle et son âge d’expiration.

Note En règle générale, vous devez éviter d’utiliser RpcNsMgmtHandleSetExpAge. Au lieu de cela, vous devez vous fier à l’âge d’expiration global de l’application. Si vous définissez l’âge de l’expiration du handle sur une petite valeur, les opérations suivantes du service de noms mettent à jour fréquemment les données locales pour tout attribut name-service demandé par votre application. Par exemple, la définition de l’âge d’expiration sur 0 force l’opération suivante à mettre à jour les données locales pour l’attribut name-service demandé par votre application. Par conséquent, la définition d’un petit âge d’expiration de handle peut créer des problèmes de performances pour votre application. En outre, si votre application utilise un serveur de service de noms distant, un petit âge d’expiration peut nuire aux performances réseau de toutes les applications.

 

Limitez l’utilisation de RpcNsMgmtHandleSetExpAge aux situations suivantes :

• Quand vous devez toujours obtenir des données de service de nom précises.

  Par exemple, pendant les opérations de gestion de mise à jour d’un profil, vous devrez peut-être toujours voir le contenu actuel du profil. Dans ce cas, avant de commencer à se renseigner sur un profil, votre application doit appeler la fonction RpcNsMgmtHandleSetExpAge et spécifier 0 pour le paramètre ExpirationAge .

• Lorsqu’une requête utilisant l’âge d’expiration par défaut a échoué et que votre application doit réessayer l’opération.

  Par exemple, une application cliente utilisant des opérations d’importation de service de nom doit d’abord essayer d’obtenir des liaisons à l’aide de l’âge d’expiration par défaut de l’application. Toutefois, parfois, l’opération import-next ne retourne aucun handle de liaison ou un nombre insuffisant d’entre eux. Dans ce cas, le client peut réessayer l’opération d’importation et, après l’appel RpcNsBindingImportBegin , inclure un appel RpcNsMgmtHandleSetExpAge et spécifier 0 pour le paramètre ExpirationAge . Lorsque le client appelle à nouveau la fonction import-next, l’âge d’expiration de poignée réduit entraîne la mise à jour des données d’attribut local par l’opération import-next.

Spécifications

Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	rpcnsi.h (inclure Rpc.h)
Bibliothèque	Rpcns4.lib
DLL	Rpcns4.dll

Voir aussi

RpcNsBindingImportBegin

RpcNsMgmtInqExpAge

RpcNsMgmtSetExpAge