Modèle asynchrone

La plupart des opérations dans l’API Des services Web Windows peuvent être effectuées de manière synchrone ou asynchrone. Pour appeler une fonction de façon synchrone, transmettez une valeur Null pour la structure WS_ASYNC_CONTEXT . Pour spécifier qu’une fonction peut être exécutée de manière asynchrone, transmettez une WS_ASYNC_CONTEXT non null à la fonction.

Lorsqu’elle est appelée de manière asynchrone, une fonction peut néanmoins se terminer de manière synchrone ou asynchrone. Si la fonction se termine de manière synchrone, elle retourne une valeur qui indique la réussite ou l’erreur finale, et cette valeur est toujours autre que WS_S_ASYNC (voir Valeurs de retour des services Web Windows). Toutefois, une valeur de retour de WS_S_ASYNC indique que la fonction se terminera de manière asynchrone. Lorsque la fonction se termine de façon asynchrone, un rappel est appelé pour signaler l’achèvement de l’opération. Ce rappel indique la valeur finale de réussite ou d’erreur. Le rappel n’est pas appelé si l’opération se termine de manière synchrone.

Pour créer un contexte asynchrone, initialisez les champs callback et callbackState de la structure WS_ASYNC_CONTEXT . Le champ callbackState est utilisé pour spécifier un pointeur vers des données définies par l’utilisateur qui sont passées à la fonction WS_ASYNC_CALLBACK .

L’exemple suivant illustre l’appel asynchrone d’une fonction en passant un pointeur vers une structure WS_ASYNC_CONTEXT qui contient le rappel et un pointeur vers les données d’état.

HRESULT ExampleAsyncFunction(WS_ASYNC_CONTEXT* asyncContext);
void ExampleAsyncFunction()
{
    // Set up the WS_ASYNC_CONTEXT structure.
    MyState* myState = ...;  \\ Declare a pointer to user-defined data.
    WS_ASYNC_CONTEXT asyncContext;
    asyncContext.callback = MyCallback;  \\ Set the callback.
    asyncContext.callbackState = myState; \\ Set the pointer to the user-defined data.

    // Start the asynchronous operation
    HRESULT hr = SomeFunction(&asyncContext);

    if (hr == WS_S_ASYNC)
    {
        // The operation is completing asynchronously.  The callback is called 
        // when the operation is complete.
    }
    else
    {
        // The operation completed synchronously.  The callback is not called.
    }
}
void CALLBACK MyCallback(HRESULT hr, WS_CALLBACK_MODEL callbackModel, void* callbackState)
{
    MyState* myState = (MyState*)callbackState;

    // The operation completed asynchronously.
}

La structure WS_ASYNC_CONTEXT est utilisée par la fonction asynchrone uniquement pendant la durée de l’appel de fonction (et non pour la durée de l’opération asynchrone). Vous pouvez donc la déclarer en toute sécurité sur la pile.

Si d’autres paramètres, en plus de la structure WS_ASYNC_CONTEXT , sont passés à une fonction asynchrone en tant que pointeurs et que la fonction se termine de façon asynchrone, il incombe à l’appelant de conserver les valeurs pointées par ces paramètres actives (non libérées) jusqu’à ce que le rappel asynchrone soit appelé.

Il existe des limitations quant aux opérations qu’un rappel peut effectuer. Pour plus d’informations sur les opérations possibles, consultez la WS_CALLBACK_MODEL.

Lorsque vous implémentez une fonction asynchrone, n’appelez pas le rappel sur le thread qui a appelé la fonction asynchrone avant que la fonction asynchrone ne soit retournée à l’appelant, car cela perturbe le modèle asynchrone.

Lorsque vous implémentez une fonction qui doit exécuter une série d’opérations asynchrones, envisagez d’utiliser la fonction d’assistance WsAsyncExecute .

L’exemple de fonction asynchrone montre comment implémenter et utiliser des fonctions qui suivent le modèle asynchrone.

Le démarrage d’une opération d’E/S asynchrone consomme des ressources système. Si suffisamment d’opérations d’E/S sont démarrées, le système peut ne plus répondre. Pour éviter cela, une application doit limiter le nombre d’opérations asynchrones qu’elle démarre.

Le modèle asynchrone utilise les éléments d’API suivants.

Rappel	Description
WS_ASYNC_CALLBACK	Paramètre de fonction de rappel utilisé avec le modèle asynchrone.
WS_ASYNC_FUNCTION	Utilisé avec WsAsyncExecute pour spécifier la fonction suivante à appeler dans une série d’opérations asynchrones.

 

Énumération	Description
WS_CALLBACK_MODEL	Spécifie le comportement de thread d’un rappel (par exemple, un WS_ASYNC_CALLBACK).

 

Fonction	Description
WsAsyncExecute	Appelle un rappel défini par l’utilisateur qui peut lancer une opération asynchrone et indiquer une fonction qui doit être appelée une fois l’opération asynchrone terminée.

 

Structure	Description
WS_ASYNC_CONTEXT	Spécifie le rappel asynchrone et un pointeur vers des données définies par l’utilisateur, qui seront passées au rappel asynchrone.
WS_ASYNC_OPERATION	Utilisé avec WsAsyncExecute pour spécifier la fonction suivante à appeler dans une série d’opérations asynchrones.
WS_ASYNC_STATE	Utilisé par WsAsyncExecute pour gérer l’état d’une opération asynchrone.

 

Rubriques connexes

Exemple de fonction asynchrone

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute