RpcSsContextLockExclusive, fonction (rpcasync.h)
La fonction RpcSsContextLockExclusive permet à une application de commencer à utiliser un handle de contexte en mode exclusif. La fonction RpcSsContextLockExclusive permet aux méthodes déclarées comme non sérialisées (partagées) dans le fichier IDL ou ACF d’être modifiées dynamiquement pour accéder à un handle de contexte en mode sérialisé (exclusif).
Syntaxe
RPC_STATUS RpcSsContextLockExclusive(
[in] RPC_BINDING_HANDLE ServerBindingHandle,
[in] PVOID UserContext
);
Paramètres
[in] ServerBindingHandle
Handle de liaison sur le serveur qui représente une liaison à un client. Le serveur emprunte l’identité du client indiqué par ce handle. Si la valeur zéro est spécifiée, le serveur emprunte l’identité du client pris en charge par ce thread de serveur.
[in] UserContext
Pointeur passé à la routine du gestionnaire ou du serveur par RPC. Consultez la section Notes.
Pour les handles de contexte out-only, la fonction RpcSsContextLockExclusive n’effectue aucune opération.
Valeur retournée
Retourne RPC_S_OK en cas d’exécution réussie, indiquant que le thread a maintenant accès au handle de contexte en mode exclusif. Retourne ERROR_MORE_WRITES lorsque plusieurs threads tentent un verrou exclusif sur le handle de contexte. Consultez la section Notes.
Remarques
La modification d’un handle de contexte sérialisé ou non peut être utile pour les applications qui déterminent s’il faut fermer un handle de contexte en fonction des conditions détectées lors de l’exécution. Pour changer un handle de contexte de sérialisé (exclusif) en non-ialisé (partagé), utilisez la fonction RpcSsContextLockShared .
Pour le paramètre UserContext , si la routine du gestionnaire reçoit un pointeur vers un handle de contexte, elle doit passer la fonction RpcSsContextLockExclusive le pointeur qu’elle a reçu de RPC. Si la routine de gestionnaire reçoit le handle de contexte lui-même, ce qui est courant pour les handles de contexte uniquement, elle doit passer le handle de contexte lui-même à la fonction RpcSsContextLockExclusive . L’exemple de code suivant illustre ceci :
void _UseShared(
/* [in] */ handle_t Binding,
//...
/* [in] */ TestContextHandleShared *Ctx,
//...
)
{
//...
RpcStatus = RpcSsContextLockExclusive(Binding, Ctx);
//...
}
Si une routine de gestionnaire prend plusieurs handles de contexte [in, out] en tant qu’argument, RPC donne à la routine de gestionnaire un pointeur vers le handle de contexte, et non le handle de contexte lui-même. Le pointeur est garanti comme étant unique, sa transmission à la fonction RpcSsContextLockExclusive est sans ambiguïté. Toutefois, si une fonction accepte plusieurs handles de contexte [in] uniquement, RPC donne à la routine du gestionnaire le handle de contexte lui-même. Par conséquent, le handle de contexte peut ne pas être unique. Dans ce cas, RPC exécute cette fonction sur le premier handle de contexte avec la valeur donnée.
Les méthodes ne doivent pas modifier un handle de contexte en mode partagé. L’appel de la fonction RpcSsContextLockExclusive n’élimine pas un verrou de lecteur sur le handle de contexte spécifié ; Cela garantit un handle de contexte inchangé pour les applications qui ne modifient pas les handles de contexte en mode partagé. Si deux threads tentent d’obtenir un verrou exclusif sur le même handle de contexte en appelant la fonction RpcSsContextLockExclusive en même temps, un thread choisi arbitrairement est retourné RPC_S_OK et l’autre est retourné ERROR_MORE_WRITES. Le thread retourné ERROR_MORE_WRITES reçoit un verrou exclusif, mais son verrou de lecteur sur le handle de contexte est perdu au retour. Un appelant recevant ERROR_MORE_WRITES ne doit rien supposer du handle de contexte lors du retour de la fonction RpcSsContextLockExclusive , car elle a peut-être été détruite.
Les appels asynchrones ne doivent pas utiliser la fonction RpcSsContextLockExclusive sur le même objet d’appel à partir de plusieurs threads à la fois.
La fonction RpcSsContextLockExclusive peut échouer en raison de conditions de mémoire insuffisante, et les serveurs RPC doivent donc être prêts à gérer ces erreurs.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | rpcasync.h (inclure Rpc.h) |
| Bibliothèque | Rpcrt4.lib |
| DLL | Rpcrt4.dll |