Operações e notificações assíncronas
Para operações que podem ser lentas ou computacionalmente caras, o SDK de Lobby e Matchmaking do PlayFab expõe APIs assíncronas. As APIs assíncronas permitem iniciar operações caras ou lentas a partir dos seus threads principais e sondar a conclusão dessas operações em um thread de sua escolha. Esse mesmo mecanismo de sondagem também é usado para entregar notificações assíncronas de atualizações do SDK ao código do seu título. Esta página apresenta uma visão geral dos padrões de API assíncrona do SDK de Lobby e Matchmaking do PlayFab e das práticas recomendadas para programar com eles.Padrões básicos de API
Há dois tipos de padrões de API assíncrona a serem considerados no SDK de Lobby e Matchmaking do PlayFab:Operações assíncronas
É simples usar as APIs assíncronas do SDK. O padrão geral para iniciar e concluir operações assíncronas é o seguinte:- Faça uma chamada de método normal à API assíncrona apropriada de sua escolha. As operações assíncronas comuns que você provavelmente usará incluem:
- Verifique o valor de retorno HRESULT da API com as macros SUCCEEDED() ou FAILED(). Esse valor retornado de forma síncrona informará se a operação foi iniciada com êxito.
- Sonde a conclusão da operação assíncrona procurando a “alteração de estado de conclusão” associada à operação, que será fornecida por PFMultiplayerStartProcessingLobbyStateChanges() ou PFMultiplayerStartProcessingMatchmakingStateChanges. Um exemplo da “alteração de estado de conclusão” associada a PFMultiplayerCreateAndJoinLobby() é PFLobbyCreateAndJoinLobbyCompletedStateChange. Informações mais detalhadas sobre o que são as “alterações de estado” e como elas funcionam podem ser encontradas na seção Alterações de estado.
- Verifique o valor result da alteração de estado de conclusão para determinar se a operação teve êxito ou falhou. Informações mais detalhadas sobre esses valores de erro podem ser encontradas na documentação de tratamento de erros do SDK.
Notificações assíncronas
Alguns recursos geram notificações assíncronas de alterações no SDK de Lobby e Matchmaking. As notificações comuns incluem:- Notificações de atualização do lobby.
- Notificações de desconexão do lobby.
- Notificações de alteração de status do tíquete de matchmaking.
Alterações de estado
O modelo de API assíncrona do SDK de Lobby e Matchmaking é construído em torno das structs PFLobbyStateChange e PFMatchmakingStateChange. As PFLobbyStateChanges notificam você sobre alterações no subsistema de lobby, e as PFMatchmakingStateChanges notificam você sobre alterações no subsistema de matchmaking. Essas “alterações de estado” são notificações assíncronas de eventos do SDK. Essas notificações são enfileiradas internamente, e você as processa chamando PFMultiplayerStartProcessingLobbyStateChanges() e PFMultiplayerStartProcessingMatchmakingStateChanges. Essas funções retornarão todas as alterações de estado enfileiradas (do respectivo subsistema de API) como listas que você pode percorrer e processar individualmente. Cada alteração de estado tem um campo stateChangeType correspondente que pode ser inspecionado para determinar sobre qual alteração de estado específica você está sendo notificado. Depois de saber qual alteração de estado você recebeu, poderá converter a struct genérica PFLobbyStateChange ou PFMatchmakingStateChange em um tipo mais específico de struct de alteração de estado para inspecionar os dados específicos desse evento. Normalmente, o processamento de alterações de estado é implementado como uma simples instrução switch que delega cada alteração de estado a um manipulador. Depois que a lista de alterações de estado de PFMultiplayerStartProcessingLobbyStateChanges ou PFMultiplayerStartProcessingMatchmakingStateChanges for processada, ela precisará ser devolvida a PFMultiplayerFinishProcessingMatchmakingStateChanges() ou PFMultiplayerFinishProcessingMatchmakingStateChanges(), respectivamente.Contextos de operações assíncronas
Cada API assíncrona inclui um parâmetrovoid* asyncContext. Esse valor é um parâmetro de passagem que será definido
na alteração de estado de conclusão associada a essa chamada de API quando ela for fornecida por PFMultiplayerStartProcessingLobbyStateChanges()
ou PFMultiplayerStartProcessingMatchmakingStateChanges().
Esse valor oferece um mecanismo para anexar contextos arbitrários, do tamanho de um ponteiro, às suas chamadas de API assíncrona. Esses
contextos podem ser usados em muitos cenários, incluindo:
- associar dados específicos do título a uma chamada do SDK
- vincular várias operações assíncronas com um identificador compartilhado
Enfileiramento de operações
Com frequência, ao trabalhar com APIs assíncronas, várias operações assíncronas precisam ser executadas sequencialmente como parte de um fluxo assíncrono maior. No SDK de Lobby e Matchmaking, um exemplo seria criar um lobby e enviar convites aos seus amigos para esse lobby. De forma serializada, esse fluxo seria:- Chamar PFMultiplayerCreateAndJoinLobby() para criar um lobby do PlayFab e ingressar nele.
- Aguardar a PFLobbyCreateAndJoinLobbyCompletedStateChange refletir que o lobby foi criado e ingressado com êxito.
- Chamar PFLobbySendInvite() para cada amigo convidado.
- Aguardar a PFLobbySendInviteCompletedStateChange refletir que o convite foi enviado com êxito.
