RpcBindingBind, fonction (rpcasync.h)

Article
03/04/2024

La fonction RpcBindingBind contacte un serveur RPC et y est liée.

Syntaxe

RPC_STATUS RpcBindingBind(
  [in, optional] PRPC_ASYNC_STATE   pAsync,
  [in]           RPC_BINDING_HANDLE Binding,
  [in]           RPC_IF_HANDLE      IfSpec
);

Paramètres

[in, optional] pAsync

Pointeur vers la structure RPC_ASYNC_STATE qui contient des informations d’appel asynchrones. Ces informations d’état contiennent la méthode d’achèvement utilisée pour signaler quand l’opération de liaison est terminée.

[in] Binding

RPC_BINDING_HANDLE structure qui contient le handle de liaison créé avec un appel précédent à RpcBindingCreate.

[in] IfSpec

RPC_IF_HANDLE valeur qui spécifie l’interface sur laquelle les appels pour ce handle de liaison seront effectués.

Valeur retournée

Cette fonction retourne RPC_S_OK en cas de réussite ; sinon, un code d’erreur RPC_S_* est retourné. Pour plus d’informations sur ces codes d’erreur, consultez Valeurs de retour RPC.

Code de retour	Description
RPC_S_OK	Le RPC est correctement lié au serveur et des appels distants peuvent être effectués.
RPC_S_CANNOT_SUPPORT	Une fonctionnalité obsolète de RPC a été demandée pour cette opération de liaison.

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

Remarques

RpcBindingBind contacte le serveur RPC et le lie à l’aide du handle de liaison retourné par un appel précédent à RpcBindingCreate. Les handles de liaison établis à l’aide de cette méthode sont appelés handles de liaison « rapides ».

Si la valeur du paramètre pAsync n’est pas NULL, la liaison est asynchrone et les appels à RpcAsyncCancelCall et RpcAsyncGetCallStatus peuvent être effectués sur l’état asynchrone fourni. Méthode d’achèvement spécifiée dans les informations d’état asynchrone wis utilisées pour signaler à l’appelant que la liaison est terminée. Après notification d’achèvement, les appels peuvent être effectués à l’aide du descripteur de liaison nouvellement lié.

La méthode bind ne détermine pas quels appels peuvent être effectués à l’aide du handle de liaison : si la liaison est synchrone, des appels asynchrones peuvent toujours être effectués sur le handle de liaison, et vice versa. La méthode bind détermine comment la notification d’une liaison réussie est signalée, en particulier dans le cas de liaisons asynchrones.

Étant donné que cette API échange des messages avec le serveur RPC, les opérations de liaison peuvent prendre beaucoup de temps en fonction d’un certain nombre de facteurs indépendants, notamment le trafic réseau et le blocage du serveur. Si la liaison est synchrone, l’opération de liaison peut se bloquer si le serveur est bloqué.

Une fois la liaison terminée, la sémantique des appels effectués sur le handle de liaison est identique aux appels effectués sur tout autre type de handle de liaison, mais avec quatre différences notables, répertoriées ci-dessous :

Tous les appels sur ce handle de liaison doivent être effectués sur l’interface spécifiée dans IfSpec. Le handle de liaison est lié de manière unique à cette interface. L’interface elle-même peut être déchargée avant la destruction du handle de liaison, mais des informations détaillées sur l’interface sont mises en cache dans le handle de liaison, et si un appel est effectué sur le même handle de liaison pour une autre interface, les résultats ne sont pas définis.
Les rappels RPC ne sont pas autorisés sur un handle de liaison. Si le serveur RPC tente d’effectuer un rappel à l’aide d’une méthode avec l’attribut [callback], l’appel est rejeté avec l’erreur RPC_S_CANNOT_SUPPORT status code.
Avec les handles de liaison classiques, RPC tente de se reconnecter en toute transparence au serveur si la connexion est supprimée. Pour les handles de liaison rapide, RPC ne tente pas de se reconnecter en toute transparence au serveur ; au lieu de cela, elle retourne l’une des erreurs suivantes : RPC_S_SERVER_UNAVAILABLE, RPC_S_CALL_FAILED et RPC_C_CALL_FAILED_DNE. Si la connexion est supprimée en raison d’informations d’identification rejetées, RPC_S_ACCESS_DENIED est retourné ; et si le serveur rencontre une erreur temporaire en raison d’un manque de mémoire, RPC_S_OUT_OF_MEMORY est retourné. Toutes les autres erreurs de connectivité sont le résultat d’erreurs de marshaling ou de démarshalation retournées par les routines de serveur. En cas de perte de connexion, l’appelé doit annuler la liaison en appelant RpcBindingUnbind , puis rebiner avec un autre appel à RpcBindingBind.

Si l’appel à RpcBindingBind échoue, le handle de liaison n’est pas lié au serveur et l’appelant peut tenter de lier à nouveau avec un autre appel à la même API, ou il peut libérer le handle de liaison. Étant donné qu’une opération de liaison ayant échoué ne déplace pas le handle de liaison vers l’état lié, RpcBindingUnbind ne doit pas être appelé sur celui-ci.

Certaines fonctions ne doivent pas être appelées tant que l’opération de liaison n’a pas signalé l’achèvement, en particulier :

Note Actuellement, cette fonction prend uniquement en charge la séquence de protocole ncalrpc .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP2 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2008, Windows Server 2003 avec SP1 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	rpcasync.h (inclure Rpc.h)
Bibliothèque	Rpcrt4.lib
DLL	Rpcrt4.dll

Voir aussi

RpcBindingCreate

RpcBindingUnbind

Partager via