Operaciones y notificaciones asincrónicas
Para las operaciones que pueden ser lentas o costosas desde el punto de vista computacional, el SDK de PlayFab Lobby y Matchmaking expone API asincrónicas. Las API asincrónicas le permiten iniciar operaciones costosas o lentas desde los subprocesos principales y sondear la finalización de esas operaciones en el subproceso que elija. Este mismo mecanismo de sondeo también se usa para entregar notificaciones asincrónicas de actualizaciones del SDK al código del título. Esta página ofrece una visión general de los patrones de API asincrónicas del SDK de PlayFab Lobby y Matchmaking y los procedimientos recomendados para programar con ellos.Patrones básicos de API
Hay dos tipos de patrones de API asincrónicas que debe tener en cuenta en el SDK de PlayFab Lobby y Matchmaking:Operaciones asincrónicas
Usar las API asincrónicas del SDK es sencillo. El patrón general para iniciar y completar operaciones asincrónicas es el siguiente:- Realice una llamada de método normal a la API asincrónica adecuada de su elección. Entre las operaciones asincrónicas comunes que probablemente utilizará se incluyen:
- Compruebe el valor devuelto HRESULT de la API con las macros SUCCEEDED() o FAILED(). Este valor devuelto de forma sincrónica le indicará si la operación se ha iniciado correctamente.
- Sondee la finalización de la operación asincrónica buscando el “cambio de estado de finalización” de la operación asociada proporcionado por PFMultiplayerStartProcessingLobbyStateChanges() o PFMultiplayerStartProcessingMatchmakingStateChanges. Un ejemplo del “cambio de estado de finalización” asociado a PFMultiplayerCreateAndJoinLobby() es PFLobbyCreateAndJoinLobbyCompletedStateChange. Puede encontrar información más detallada sobre qué son los “cambios de estado” y cómo funcionan en la sección Cambios de estado.
- Compruebe el valor result del cambio de estado de finalización para determinar si la operación se realizó correctamente o falló. Puede encontrar información más detallada sobre estos valores de error en la documentación de control de errores del SDK.
Notificaciones asincrónicas
Algunas características generarán notificaciones asincrónicas de cambios en el SDK de Lobby y Matchmaking. Entre las notificaciones comunes se incluyen:- Notificaciones de actualización del lobby.
- Notificaciones de desconexión del lobby.
- Notificaciones de cambio de estado del ticket de matchmaking.
Cambios de estado
El modelo de API asincrónicas del SDK de Lobby y Matchmaking se basa en las estructuras PFLobbyStateChange y PFMatchmakingStateChange. Los PFLobbyStateChanges le notifican los cambios en el subsistema de lobby y los PFMatchmakingStateChanges le notifican los cambios en el subsistema de matchmaking. Estos “cambios de estado” son notificaciones asincrónicas de eventos del SDK. Estas notificaciones se ponen en cola internamente y usted las procesa llamando a PFMultiplayerStartProcessingLobbyStateChanges() y a PFMultiplayerStartProcessingMatchmakingStateChanges. Estas funciones devolverán todos los cambios de estado en cola (para su respectivo subsistema de API) como listas que puede recorrer y procesar individualmente. Cada cambio de estado tiene un campo stateChangeType correspondiente que se puede inspeccionar para determinar de qué cambio de estado específico se le está notificando. Una vez que sepa qué cambio de estado se le ha proporcionado, puede convertir la estructura genérica PFLobbyStateChange o PFMatchmakingStateChange en un tipo de estructura de cambio de estado más específico para inspeccionar los datos concretos de ese evento. Normalmente, el procesamiento de cambios de estado se implementa como una simple instrucción switch que delega cada cambio de estado en un controlador. Una vez que la lista de cambios de estado se ha procesado desde PFMultiplayerStartProcessingLobbyStateChanges o PFMultiplayerStartProcessingMatchmakingStateChanges, debe devolverse a PFMultiplayerFinishProcessingMatchmakingStateChanges() o a PFMultiplayerFinishProcessingMatchmakingStateChanges(), respectivamente.Contextos de operaciones asincrónicas
Cada API asincrónica incluye un parámetrovoid* asyncContext. Este valor es un parámetro de paso directo que se establecerá
en el cambio de estado de finalización asociado a esta llamada de API cuando lo proporcione PFMultiplayerStartProcessingLobbyStateChanges()
o PFMultiplayerStartProcessingMatchmakingStateChanges().
Este valor le proporciona un mecanismo para adjuntar contextos arbitrarios del tamaño de un puntero a sus llamadas de API asincrónicas. Estos
contextos se pueden usar en muchos escenarios, entre los que se incluyen:
- asociar datos específicos del título a una llamada del SDK
- vincular varias operaciones asincrónicas con un identificador compartido
Puesta en cola de operaciones
Con frecuencia, al trabajar con API asincrónicas, varias operaciones asincrónicas deben ejecutarse secuencialmente como parte de un flujo asincrónico más amplio. En el SDK de Lobby y Matchmaking, un ejemplo sería crear un lobby y enviar invitaciones a sus amigos para ese lobby. Serializado, este flujo tendría el siguiente aspecto:- Llame a PFMultiplayerCreateAndJoinLobby() para crear un lobby de PlayFab y unirse a él.
- Espere a que PFLobbyCreateAndJoinLobbyCompletedStateChange refleje que el lobby se creó y se unió correctamente.
- Llame a PFLobbySendInvite() para cada amigo invitado.
- Espere a que PFLobbySendInviteCompletedStateChange refleje que la invitación se envió correctamente.
