> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide des opérations asynchrones du SDK C++ Lobby et Matchmaking

> Comprenez les opérations asynchrones, l'interrogation et les notifications de changement d'état dans le SDK C++ PlayFab Lobby et Matchmaking, avec les pratiques exemplaires pour les titres multijoueurs.

# Opérations et notifications asynchrones

Pour les opérations susceptibles d'être lentes ou coûteuses en calcul, le SDK PlayFab Lobby et Matchmaking expose des API
asynchrones. Les API asynchrones vous permettent de démarrer des opérations coûteuses ou lentes depuis vos threads principaux et d'interroger
l'achèvement de ces opérations sur le thread de votre choix. Ce même mécanisme d'interrogation sert également à transmettre
à votre code de titre des notifications asynchrones de mises à jour du SDK. Cette page présente les modèles d'API asynchrones du SDK PlayFab Lobby et
Matchmaking ainsi que les pratiques exemplaires de programmation associées.

## Modèles d'API de base

Il existe deux types de modèles d'API asynchrones à connaître dans le SDK PlayFab Lobby et Matchmaking :

1. [Opérations asynchrones](#asynchronous-operations)
2. [Notifications asynchrones](#asynchronous-notifications)

<a id="asynchronous-operations" />

### Opérations asynchrones

Les API asynchrones du SDK sont simples à utiliser. Le modèle général de démarrage et d'achèvement des opérations
asynchrones est le suivant :

1. Effectuez un appel de méthode normal à l'API asynchrone appropriée de votre choix. Parmi les opérations asynchrones courantes
   que vous utiliserez probablement, citons :
   * [PFMultiplayerCreateAndJoinLobby](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayercreateandjoinlobby).
   * [PFMultiplayerJoinLobby](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerjoinlobby).
   * [PFLobbyPostUpdate](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pflobbypostupdate).
   * [PFMultiplayerCreateMatchmakingTicket](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreatematchmakingticket).

2. Vérifiez la valeur de retour **HRESULT** de l'API à l'aide des macros **SUCCEEDED()** ou **FAILED()**. Cette valeur retournée
   de façon synchrone vous indique si l'opération a bien démarré.

<Warning>
  La valeur de retour synchrone d'un appel d'API asynchrone ne vous indique **PAS** si l'opération s'est terminée avec succès. Pour plus de renseignements sur les erreurs synchrones et asynchrones, consultez la [documentation sur la gestion des erreurs](/fr-CA/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors#synchronous-vs-asynchronous-errors) du SDK.
</Warning>

3. Interrogez l'achèvement de l'opération asynchrone en attendant que le « changement d'état d'achèvement » de l'opération associée
   soit fourni par [PFMultiplayerStartProcessingLobbyStateChanges()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges)
   or [PFMultiplayerStartProcessingMatchmakingStateChanges](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges).
   Un exemple de « changement d'état d'achèvement » associé à **PFMultiplayerCreateAndJoinLobby()** est
   [PFLobbyCreateAndJoinLobbyCompletedStateChange](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbycreateandjoinlobbycompletedstatechange).
   Des informations plus détaillées sur ce que sont les « changements d'état » et sur leur fonctionnement sont disponibles dans la
   section [Changements d'état](#state-changes).

4. Vérifiez la valeur **result** du changement d'état d'achèvement pour déterminer si l'opération a réussi ou échoué.
   Des informations plus détaillées sur ces valeurs d'erreur sont disponibles dans la [documentation sur la gestion des erreurs](/fr-CA/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors#synchronous-vs-asynchronous-errors) du SDK.

<a id="asynchronous-notifications" />

### Notifications asynchrones

Certaines fonctionnalités génèrent des notifications asynchrones de modifications dans le SDK Lobby et Matchmaking.

Les notifications courantes sont notamment :

1. [Notifications de mise à jour du lobby](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbyupdatedstatechange).
2. [Notifications de déconnexion du lobby](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbydisconnectingstatechange).
3. [Notifications de changement d'état des tickets de matchmaking](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange).

Ces notifications asynchrones vous sont fournies par le SDK sous forme de « changements d'état » au moyen de
[PFMultiplayerStartProcessingLobbyStateChanges()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges)
and [PFMultiplayerStartProcessingMatchmakingStateChanges](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges).

Des informations plus détaillées sur ce que sont les « changements d'état » et sur leur fonctionnement sont disponibles dans la section [Changements d'état](#state-changes).

<a id="state-changes" />

## Changements d'état

Le modèle d'API asynchrone du SDK Lobby et Matchmaking repose sur les structs [PFLobbyStateChange](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbystatechange)
and [PFMatchmakingStateChange](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingstatechange)
. Les **PFLobbyStateChanges** vous informent des modifications du sous-système de lobby et les **PFMatchmakingStateChanges**
vous informent des modifications du sous-système de matchmaking.

Ces « changements d'état » sont des notifications asynchrones d'événements provenant du SDK. Ces notifications sont
mises en file d'attente en interne, et vous les traitez en appelant [PFMultiplayerStartProcessingLobbyStateChanges()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges)
and [PFMultiplayerStartProcessingMatchmakingStateChanges](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges).
Ces fonctions retournent tous les changements d'état en file d'attente (pour leur sous-système d'API respectif) sous forme de listes que vous pouvez
parcourir et traiter individuellement. Chaque changement d'état possède un champ *stateChangeType* correspondant, que vous pouvez
examiner pour déterminer le changement d'état spécifique dont vous êtes informé. Une fois que vous savez quel changement d'état
vous a été fourni, vous pouvez convertir le struct générique **PFLobbyStateChange** ou **PFMatchmakingStateChange** en
un type de struct de changement d'état plus spécifique afin d'examiner les données propres à cet événement.

En général, le traitement des changements d'état est implémenté sous la forme d'une simple instruction switch qui délègue chaque changement d'état à un
gestionnaire.

Une fois traitée, la liste des changements d'état obtenue de **PFMultiplayerStartProcessingLobbyStateChanges** ou de **PFMultiplayerStartProcessingMatchmakingStateChanges**
doit être retournée à [PFMultiplayerFinishProcessingMatchmakingStateChanges()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges)
or [PFMultiplayerFinishProcessingMatchmakingStateChanges()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges),
respectivement.

```cpp theme={null}
//
// Process Lobby state changes
//
uint32_t lobbyStateChangeCount;
const PFLobbyStateChange * const * lobbyStateChanges;
HRESULT hr = PFMultiplayerStartProcessingLobbyStateChanges(m_pfmHandle, &lobbyStateChangeCount, &lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < lobbyStateChangeCount; ++i)
{
    const PFLobbyStateChange* stateChange = lobbyStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFLobbyStateChangeType::CreateAndJoinLobbyCompleted:
        {
            HandleCreateAndJoinLobbyCompleted(
                static_cast<const PFLobbyCreateAndJoinLobbyCompletedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingLobbyStateChanges(m_pfmHandle, lobbyStateChangeCount, lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

//
// Process Match state changes
//
uint32_t matchStateChangeCount;
const PFMatchmakingStateChange * const * matchStateChanges;
hr = PFMultiplayerStartProcessingMatchmakingStateChanges(m_pfmHandle, &matchStateChangeCount, &matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < matchStateChangeCount; ++i)
{
    const PFMatchmakingStateChange* stateChange = matchStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFMatchmakingStateChangeType::TicketStatusChanged:
        {
            HandleMatchmakingTicketStatusChanged(
                static_cast<const PFMatchmakingTicketStatusChangedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(m_pfmHandle, matchStateChangeCount, matchStateChanges);
if (FAILED(hr))
{
    return hr;
}
```

## Contextes des opérations asynchrones

Chaque API asynchrone comprend un paramètre `void* asyncContext`. Cette valeur est un paramètre transmis tel quel, qui sera défini
dans le changement d'état d'achèvement associé à cet appel d'API lorsqu'il sera fourni par **PFMultiplayerStartProcessingLobbyStateChanges()**
ou **PFMultiplayerStartProcessingMatchmakingStateChanges()**.

Cette valeur vous offre un mécanisme permettant d'attacher des contextes arbitraires de la taille d'un pointeur à vos appels d'API asynchrones. Ces
contextes peuvent être utilisés dans de nombreux scénarios, notamment :

1. associer des données propres au titre à un appel du SDK
2. relier plusieurs opérations asynchrones à l'aide d'un identifiant partagé

Ces contextes asynchrones ne sont pas obligatoires pour utiliser le SDK, mais ils peuvent faciliter l'écriture de certaines logiques de titre.

## Mise en file d'attente des opérations

Souvent, lors de l'utilisation d'API asynchrones, plusieurs opérations asynchrones doivent s'exécuter séquentiellement dans le cadre
d'un flux asynchrone plus large.

Dans le SDK Lobby et Matchmaking, un exemple serait la création d'un lobby et l'envoi d'invitations à vos amis pour
ce lobby. De façon séquentielle, ce flux se présenterait ainsi :

1. Appeler **PFMultiplayerCreateAndJoinLobby()** pour créer et rejoindre un lobby PlayFab.
2. Attendre que **PFLobbyCreateAndJoinLobbyCompletedStateChange** indique que le lobby a bien été créé et rejoint.
3. Appeler **PFLobbySendInvite()** pour chaque ami invité.
4. Attendre que **PFLobbySendInviteCompletedStateChange** indique que l'invitation a bien été envoyée.

Pour des flux et une logique de titre plus complexes, ce modèle séquentiel peut être approprié. Toutefois, pour des flux plus simples,
le SDK propose une alternative destinée à simplifier le code du titre :

De nombreuses API asynchrones du SDK prennent en charge la mise en file d'attente d'opérations dépendantes avant qu'une opération précédente ne soit
entièrement terminée. Dans l'exemple précédent, vous pouvez envoyer une invitation pour un lobby avant d'avoir constaté que
le lobby a bien été créé.

En pratique, la mise en file d'attente vous permet de regrouper un ensemble d'opérations asynchrones, de les lancer toutes en même temps
et de centraliser la gestion des erreurs en un seul point d'échec.

```cpp theme={null}
PFLobbyHandle newLobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobby(m_pfmHandle, myPlayerEntityId, newLobbyConfiguration, nullptr, nullptr, &newLobby);
if (SUCCEEDED(hr))
{
    for (size_t i = 0; SUCCEEDED(hr) && i < friends.size(); ++i)
    {
        hr = PFLobbySendInvite(m_pfmHandle, myPlayerEntityId, friends[i], nullptr);
    }

    if (SUCCEEDED(hr))
    {
        m_lobby = newLobby;
        Log("Created lobby and invited %zu friends!", friends.size());
    }
    else
    {
        // For the purposes of demonstration, we could have a policy that we shouldn't bother with any lobbies where
        // we couldn't invite all of our friends.
        (void) PFLobbyLeave(newLobby, myPlayerEntityId, nullptr);
    }
}
```

## Contrôle du travail asynchrone

Il est parfois nécessaire que les titres contrôlent l'endroit où le travail asynchrone est effectué, afin d'éviter la contention du processeur entre
les bibliothèques et les charges de travail processeur principales du titre.

Le SDK Lobby et Matchmaking vous permet de contrôler l'exécution du travail asynchrone au moyen du
[Contrôle de l'affinité des threads](#controlling-thread-affinity)

<a id="controlling-thread-affinity" />

### Contrôle de l'affinité des threads

Par défaut, le travail asynchrone du SDK est effectué sur des threads d'arrière-plan soigneusement contrôlés. Certains titres ont besoin
d'un contrôle grossier sur l'*emplacement* où ces threads d'arrière-plan sont planifiés, afin d'éviter la contention du processeur.

Pour ces titres, le SDK Lobby et Matchmaking fournit
[PFMultiplayerSetThreadAffinityMask()](/fr-CA/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetthreadaffinitymask).
Sur les plateformes prises en charge, cela vous permet de limiter les cœurs de processeur utilisés pour les threads d'arrière-plan du SDK.
Vous pouvez ainsi garantir que certains cœurs sont réservés à vos propres charges de travail processeur, sans aucune contention.


## Related topics

- [Gestion des erreurs du SDK C++ Lobby et Matchmaking](/fr-CA/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors.md)
- [Rechercher des lobbies](/fr-CA/services/playfab/multiplayer/lobby/find-lobbies.md)
- [Rejoindre des lobbies](/fr-CA/services/playfab/multiplayer/lobby/join-lobbies.md)
- [Démarrage rapide du SDK Lobby](/fr-CA/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [Intégrer Party à Lobby à l'aide du SDK Multiplayer](/fr-CA/services/playfab/multiplayer/networking/party-lobby-integration.md)