WsAsyncExecute, fonction (webservices.h)

Fonction d’assistance pour l’implémentation d’une opération asynchrone .

Syntaxe

HRESULT WsAsyncExecute(
  [in]           WS_ASYNC_STATE         *asyncState,
  [in, optional] WS_ASYNC_FUNCTION      operation,
  [in]           WS_CALLBACK_MODEL      callbackModel,
  [in]           void                   *callbackState,
  [in, optional] const WS_ASYNC_CONTEXT *asyncContext,
  [in, optional] WS_ERROR               *error
);

Paramètres

[in] asyncState

Pointeur vers la structure WS_ASYNC_STATE utilisée pendant l’opération asynchrone. Il s’agit d’un paramètre de maintenance d’état qui n’est pas destiné à une utilisation directe. L’application doit allouer la structure WS_ASYNC_STATE et s’assurer qu’elle est maintenue en vie pendant toute l’opération asynchrone. La structure WS_ASYNC_STATE peut être réutilisée une fois qu’une opération asynchrone est terminée.

[in, optional] operation

Représente l’opération asynchrone initiale à effectuer.

[in] callbackModel

Indique si le rappel est appelé long ou court. Pour plus d’informations, consultez WS_CALLBACK_MODEL

[in] callbackState

Pointeur void vers une valeur définie par l’utilisateur qui est passée à chaque WS_ASYNC_FUNCTION.

[in, optional] asyncContext

Pointeur vers les informations permettant d’appeler la fonction de manière asynchrone. Passez la valeur NULL pour appeler la fonction de manière synchrone.

[in, optional] error

Pointeur vers une structure de WS_ERROR qui reçoit des informations d’erreur supplémentaires en cas d’échec de la fonction.

Valeur retournée

Si la fonction réussit, elle retourne NO_ERROR ; sinon, il retourne un code d’erreur HRESULT.

Remarques

Pour comprendre comment WWSAPI gère les opérations asynchrones, consultez la rubrique Modèle asynchrone .

Dans de nombreux cas, une opération asynchrone est composée d’autres opérations asynchrones. Chaque opération asynchrone peut retourner WS_S_ASYNC indiquant que le rappel sera appelé, ou tout autre code de réussite ou d’échec, auquel cas le rappel ne sera pas appelé. L’opération doit être préparée à accepter une WS_ASYNC_CONTEXT NULL indiquant que l’appelant demande l’opération à effectuer de manière synchrone. Il doit également s’assurer que le rappel est appelé de manière appropriée. Dans les opérations asynchrones complexes, WsAsyncExecute simplifie ces détails.

WsAsyncExecute fonctionne en appelant un rappel défini par l’utilisateur qui peut lancer une opération asynchrone et indiquer une fonction à appeler une fois l’opération asynchrone terminée. Cette séquence continue jusqu’à ce que le rappel ne définisse pas une autre fonction à appeler. À ce stade, le rappel spécifié par le WS_ASYNC_CONTEXT sera appelé si l’une des opérations s’est terminée de manière asynchrone.

Le paramètre WS_ASYNC_STATE est utilisé par WsAsyncExecute pour conserver son état et n’est pas destiné à être initialisé, inspecté ou utilisé par l’appelant. Toutefois, l’appelant doit allouer le WS_ASYNC_STATE et s’assurer qu’il est maintenu en vie pendant toute l’opération asynchrone. Le WS_ASYNC_STATE peut être réutilisé une fois l’opération asynchrone terminée.

Les exemples AsyncAdd3ExplicitExample et AsyncAdd3ImplicitExample illustrent l’implémentation manuelle de la même fonction asynchrone à l’aide de WsAsyncExecute.

Configuration requise