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

# Tarefas de multijogador

> Exemplos de código para tarefas comuns do Multiplayer de 2015: assinar alterações do MPSD, criar sessões, enviar convites, entrar em sessões, tíquetes de matchmaking e atividade.

Este tópico descreve como implementar tarefas específicas relacionadas ao uso do Multiplayer de 2015.

Este tópico aborda o seguinte:

* [Assinar notificações de alteração de sessão do Multiplayer Session Directory (MPSD)](#sfmscn)
* [Criar uma sessão do MPSD](#cams)
* [Definir um árbitro para uma sessão do MPSD](#set-an-arbiter-for-an-mpsd-session)
* [Gerenciar a ativação do título](#mta)
* [Tornar o usuário disponível para entrada](#mtuj)
* [Enviar convites de jogo](#sgi)
* [Entrar em uma sessão de jogo a partir de uma sessão de lobby](#jagsfals)
* [Entrar em uma sessão do MPSD a partir de uma ativação do título](#jamsfata)
* [Definir a atividade atual do usuário](#stuca)
* [Atualizar uma sessão do MPSD](#update-an-mpsd-session)
* [Sair de uma sessão do MPSD](#lams)
* [Preencher vagas abertas na sessão durante o matchmaking](#fossdm)
* [Criar um tíquete de partida](#camt)
* [Obter o status do tíquete de partida](#gmts)

## Assinar notificações de alteração de sessão do Multiplayer Session Directory (MPSD)

> [!NOTE]
>
> Assinar alterações em uma sessão exige que o jogador associado esteja ativo na sessão. O campo `connectionRequiredForActiveMembers` também deve estar definido como `true` no objeto `/constants/system/capabilities` da sessão. Esse campo geralmente é definido no modelo de sessão. Para obter mais informações, veja [Modelos de sessão multiplayer](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/concepts/live-session-templates.md) e [Visão geral do Multiplayer Session Directory](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md).

Para receber notificações de alteração de sessão do MPSD, o título pode usar o procedimento a seguir.

1. Use o mesmo objeto `XblContextHandle` para todas as chamadas do mesmo usuário. As assinaturas estão vinculadas ao tempo de vida desse objeto. Se houver vários usuários locais, use um objeto `XblContextHandle` separado para cada usuário.

2. Implemente manipuladores de eventos para [XblMultiplayerAddSessionChangedHandler](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayeraddsessionchangedhandler.md) e [XblMultiplayerSessionSubscriptionLostHandler](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionsubscriptionlosthandler.md).

3. Se estiver assinando alterações para mais de um usuário, adicione código ao manipulador de eventos `XblMultiplayerAddSessionChangedHandler` para evitar trabalho desnecessário. Use a propriedade [XblMultiplayerSessionChangeEventArgs](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionchangeeventargs.md)`::Branch` e a propriedade [XblMultiplayerSessionChangeEventArgs](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionchangeeventargs.md)`::ChangeNumber`. Usar essas propriedades permite acompanhar a última alteração vista e ignorar alterações mais antigas.

4. Chame [XblMultiplayerSetSubscriptionsEnabled](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersetsubscriptionsenabled.md) para permitir as assinaturas.

5. Crie um objeto de sessão local e, em seguida, entre nessa sessão como ativo.

6. Faça chamadas para cada usuário a `XblMultiplayerAddSessionChangedHandler`, passando o tipo de alteração de sessão sobre o qual deseja ser notificado.

7. Grave a sessão no MPSD conforme descrito na seção [Atualizar uma sessão do MPSD](#update-an-mpsd-session) deste tópico.

O fluxograma a seguir mostra como iniciar o multijogador assinando os eventos descritos no procedimento anterior.

![Imagem de um fluxograma que mostra como iniciar o multijogador assinando os eventos descritos no procedimento anterior.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_Start_Multiplayer.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=69f53200e2e51e3d975a3e5e7c9967fe)

### Analisando notificações de alteração de sessão duplicadas

Quando há vários usuários assinando notificações da mesma sessão, cada alteração nessa sessão dispara um shoulder tap para cada usuário.
Todos esses shoulder taps, exceto um, são duplicados.

Embora ainda recomendemos que um título assine notificações para cada usuário em uma sessão, o título deve ignorar todas as alterações sobre as quais já foi notificado. Você pode fazer isso usando as propriedades `Branch` e `ChangeNumber`.

Para detectar vários shoulder taps, um título deve fazer o seguinte:

* Armazenar o valor mais recente da propriedade `ChangeNumber` para cada valor da propriedade `Branch` avaliado.

* Se um shoulder tap tiver um valor da propriedade `ChangeNumber` maior que o último valor armazenado para aquele valor da propriedade `Branch`, processar o shoulder tap e, em seguida, atualizar o valor mais recente da propriedade `ChangeNumber`.

* Se um shoulder tap não tiver um valor da propriedade `ChangeNumber` maior para aquele valor da propriedade `Branch`, ignorar o processamento do shoulder tap. Essa alteração de sessão já foi tratada.

> [!NOTE]
>
> Os valores da propriedade `ChangeNumber` precisam ser acompanhados pelos valores da propriedade `Branch`, e não por sessão. O valor da propriedade `Branch` pode mudar durante o tempo de vida de uma sessão, redefinindo o valor da propriedade `ChangeNumber`.

[Voltar ao início deste tópico.](#top)

## Criar uma sessão do MPSD

> [!NOTE]
>
> Por padrão, uma sessão do MPSD é criada quando o primeiro membro entra nela. Se a lógica do seu título esperar que o título exista ou não exista no momento da entrada, ela poderá passar um valor de modo de gravação apropriado ao método de gravação durante a atualização da sessão.

O título deve fazer o seguinte para criar uma nova sessão.

1. Crie um novo objeto `XblContextHandle`. Seu título cria esse objeto uma vez, armazena-o e o reutiliza conforme necessário em todo o código-fonte. É necessário usar exatamente o mesmo contexto, especialmente ao trabalhar com assinaturas de sessão.

2. Crie um novo `XblMultiplayerSessionHandle` com [XblMultiplayerSessionCreateHandle](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessioncreatehandle.md) para preparar todos os dados de sessão de que o MPSD precisa para criar uma nova sessão.

3. Faça as alterações necessárias antes de gravar a sessão no MPSD. Por exemplo, ao fazer um membro entrar na sessão com uma chamada a [XblMultiplayerSessionJoin](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md), o cliente adiciona dados de solicitação locais ocultos que instruem o MPSD a realizar a entrada na chamada para atualizar a sessão.

4. Quando terminar de fazer as alterações locais, grave-as no MPSD conforme descrito na seção [Atualizar uma sessão do MPSD](#update-an-mpsd-session) deste tópico.

5. Receba do MPSD o novo objeto `XblMultiplayerSessionHandle`, com muitos campos preenchidos.

6. Use o novo objeto de sessão daqui em diante. Descarte a cópia antiga, que contém uma solicitação oculta para criar uma nova sessão.

### Exemplo

**API Flat C**

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}
```

Para obter mais informações, veja o seguinte:

* [XAsyncBlock](https://docs.xbox.com/pt-BR/reference/system/xasync/structs/xasyncblock.md)

* [XblMultiplayerSessionCreateHandle](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessioncreatehandle.md)

* [XblMultiplayerSessionInitArgs](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessioninitargs.md)

* [XblMultiplayerSessionReference](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionreference.md)

* [XblMultiplayerSessionWriteMode](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/enums/xblmultiplayersessionwritemode.md)

* [XblMultiplayerWriteSessionAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionasync.md)

* [XblMultiplayerWriteSessionResult](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionresult.md)

[Voltar ao início deste tópico.](#top)

## Definir um árbitro para uma sessão do MPSD

O título usa o procedimento a seguir para definir um árbitro para uma sessão que já foi criada.

> [!NOTE]
>
> Os tokens de dispositivo dos membros (hosts em potencial) não ficam disponíveis até que os membros tenham entrado na sessão e incluído seus endereços seguros de dispositivo.

1. Recupere do MPSD os tokens de dispositivo dos candidatos a host chamando [XblMultiplayerSessionMembers](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionmembers.md).

   > [!NOTE]
   >
   > Se a sessão tiver sido criada pelo matchmaking do SmartMatch, seus clientes poderão usar os candidatos a host disponíveis no MPSD chamando [XblMultiplayerSessionHostCandidates](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionhostcandidates.md).

2. Selecione o host desejado na lista de candidatos a host.

3. Chame [XblMultiplayerSessionSetHostDeviceToken](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionsethostdevicetoken.md) para definir o token de dispositivo no cache local do MPSD. Se a chamada para definir o token de dispositivo do host for bem-sucedida, o token de dispositivo local substituirá o token do host.

4. Se um código de status HTTP/412 for recebido ao tentar definir o token de dispositivo do host, consulte os dados da sessão. Veja se o token de dispositivo do host é do console local. Se não for do console local, outro console foi designado como árbitro.

   > [!NOTE]
   >
   > Seu cliente deve tratar o código de status HTTP/412 separadamente dos outros códigos HTTP, porque HTTP/412 não indica uma falha padrão. Para obter mais informações sobre esse código de status, veja [Códigos de status de sessões multijogador](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-status-codes.md).

5. Atualize a sessão no MPSD conforme descrito na seção [Atualizar uma sessão do MPSD](#update-an-mpsd-session) deste tópico.

   > [!NOTE]
   >
   > Se você não tiver um algoritmo melhor, o cliente poderá implementar um algoritmo guloso no qual cada candidato a host tenta se definir como host se ninguém mais tiver feito isso ainda. Para obter mais informações, veja a seção [Árbitro da sessão](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-details.md#session-arbiter) no tópico Tópicos avançados de sessões multijogador.

[Voltar ao início deste tópico.](#top)

## Gerenciar a ativação do título

O XBOX One (ou posterior) dispara o evento `CoreApplicationView.Activated` durante a ativação de protocolo.
No contexto da API multijogador, esse evento é disparado quando um usuário aceita um convite ou entra no jogo de outro usuário.
Essas ações disparam uma ativação à qual o título deve reagir levando o usuário que está entrando para o jogo com o usuário de destino.

> [!NOTE]
>
> Seu título deve esperar novos argumentos de ativação a qualquer momento e nunca deve ser codificado com base no comprimento.

O título deve executar as principais etapas a seguir para tratar a ativação do título.

1. Configure um manipulador de eventos para o evento `CoreApplicationView.Activated`. Esse manipulador é disparado sempre que ocorre uma ativação de protocolo, mesmo que o título já esteja em execução.

2. Na ativação do título, inicie uma sessão e assine as notificações de alteração da sessão. Para obter mais informações, veja [Assinar notificações de alteração de sessão do MPSD](#sfmscn) neste tópico.

3. Faça o usuário entrar na sessão como ativo. Para obter mais informações, veja [Entrar em uma sessão do MPSD a partir de uma ativação do título](#jamsfata) neste tópico.

4. Defina a sessão de lobby como a sessão de atividade exposta por meio da interface do usuário do perfil. Para obter mais informações, veja [Definir a atividade atual do usuário](#stuca) neste tópico.

5. Faça o usuário entrar na sessão de jogo como ativo. O usuário agora pode se conectar aos pares e entrar no jogo ou no lobby.

O fluxograma a seguir mostra como tratar a ativação do título.

![Imagem de um fluxograma que mostra como tratar a ativação do título.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_OnActivation.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=12c7da4ee04fdc9fe5c78471826cb9ed)

[Voltar ao início deste tópico.](#top)

## Tornar o usuário disponível para entrada

Para tornar o usuário disponível para entrada, o título deve fazer o seguinte:

1. Criar um objeto de sessão e, em seguida, modificar os atributos conforme necessário.

2. Fazer o usuário entrar na sessão como ativo. Para obter mais informações, veja [Entrar em uma sessão do MPSD a partir de uma ativação do título](#jamsfata) neste tópico.

3. Determinar se o usuário foi designado como árbitro da sessão.

4. Se o usuário não for o árbitro, ir para a etapa 7.

5. Se o usuário for o árbitro, chamar [XblMultiplayerSessionSetHostDeviceToken](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionsethostdevicetoken.md).

6. Tentar gravar a sessão usando uma chamada a [XblMultiplayerWriteSessionAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionasync.md).

7. Definir a sessão como a sessão ativa. Para obter mais informações, veja [Definir a atividade atual do usuário](#stuca) neste tópico.

O fluxograma a seguir mostra as etapas para permitir que outros jogadores entrem no jogo de um usuário durante uma partida.

![Imagem de um fluxograma que mostra as etapas para permitir que outros jogadores entrem no jogo de um usuário durante uma partida.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_Become_Joinable.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=2b2f2be1ab3913793e41659a356e5aa1)

[Voltar ao início deste tópico.](#top)

## Enviar convites de jogo

O título pode permitir que um jogador envie convites de jogo das maneiras a seguir.

* Enviar os convites para a sessão de lobby.
* Enviar os convites usando a interface do usuário genérica de convite da plataforma XBOX com a referência da sessão de jogo.

Para enviar convites de jogo para um jogador, o título deve fazer o seguinte:

1. Tornar o jogo de quem convida disponível para entrada de jogadores. Para obter mais informações, veja [Tornar o usuário disponível para entrada](#mtuj) neste tópico.

2. Determinar se os convites serão enviados pela sessão de lobby ou usando a interface do usuário de convite.

3. Se a sessão de lobby estiver sendo usada, enviar os convites usando uma chamada a [XblMultiplayerSendInvitesAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersendinvitesasync.md). Esse método pode exigir a criação de uma lista de jogadores na interface do usuário do jogo chamando [XGameUiShowPlayerPickerAsync](https://docs.xbox.com/pt-BR/reference/system/xgameui/functions/xgameuishowplayerpickerasync.md).

4. Se a interface do usuário de convite estiver sendo usada, chamar [XGameUiShowSendGameInviteAsync](https://docs.xbox.com/pt-BR/reference/system/xgameui/functions/xgameuishowsendgameinviteasync.md) para mostrar a interface do usuário de convite.

5. Tratar o [XblMultiplayerAddSessionChangedHandler](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayeraddsessionchangedhandler.md) para o jogador local depois que o jogador remoto entrar.

6. Para o jogador remoto, implementar um código de ativação do título. Para obter mais informações, veja [Gerenciar a ativação do título](#mta) neste tópico.

O fluxograma a seguir mostra como enviar convites.

![Imagem de um fluxograma que mostra como enviar convites.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_Send_Invites.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=98dd44729bea6ad14c2cc7f54f7c30a2)

[Voltar ao início deste tópico.](#top)

## Entrar em uma sessão de jogo a partir de uma sessão de lobby

As sessões de jogo em dispositivos Windows 10 devem ter a funcionalidade `userAuthorizationStyle` definida como `true` se não forem sessões grandes. Como resultado, a propriedade `joinRestriction` não pode ser `none`, o que significa que não é possível entrar diretamente na sessão de forma pública.

Um cenário comum é criar uma sessão de lobby para reunir jogadores e, em seguida, mover esses jogadores para uma sessão de jogo ou uma sessão de matchmaking. Mas, se não for possível entrar publicamente na sessão de jogo, os clientes do jogo não poderão entrar nela, a menos que atendam à configuração de `joinRestriction`. Na maioria dos casos, isso é restritivo demais para esse cenário.

A solução é usar um identificador de transferência para vincular a sessão de lobby e a sessão de jogo. O título pode fazer isso da seguinte forma:

1. Ao criar a sessão de jogo, use a API [XblMultiplayerSetTransferHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersettransferhandleasync.md) para criar um identificador de transferência que vincule a sessão de lobby e a sessão de jogo.

2. Armazene o GUID do identificador de transferência na sessão de lobby, em vez da referência de sessão da sessão de jogo.

3. Quando o título quiser mover os membros da sessão de lobby para a sessão de jogo, cada cliente usará o identificador de transferência da sessão de lobby para entrar na sessão de jogo usando a API [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md).

4. O MPSD consulta a sessão de lobby para verificar se os membros que estão tentando entrar na sessão de jogo usando o identificador de transferência também estão na sessão de lobby.

5. Se os membros estiverem na sessão de lobby, eles poderão acessar a sessão de jogo.

[Voltar ao início deste tópico.](#top)

## Entrar em uma sessão do MPSD a partir de uma ativação do título

Quando um usuário escolhe entrar na atividade de um amigo ou aceitar um convite usando a interface do usuário do shell do XBOX, o título é ativado com parâmetros que indicam em qual sessão o usuário deseja entrar. O título deve tratar essa ativação e adicionar o usuário à sessão correspondente.

Estas são as etapas que o título deve seguir.

1. Implemente um manipulador de eventos para o evento `CoreApplicationView.Activated`. Ele notifica as ativações do título.

2. Quando o manipulador for disparado, examine a propriedade `IActivatedEventArgs.Kind`. Se ela estiver definida como `Protocol`, converta os argumentos do evento para a classe `ProtocolActivatedEventArgs`.

3. Examine o objeto `ProtocolActivatedEventArgs`. Se o URI indicado na propriedade `ProtocolActivatedEventArgs.Uri` corresponder a `inviteHandleAccept` (correspondente a um convite aceito) ou a `activityHandleJoin` (correspondente a uma entrada pela interface do usuário do shell), analise a cadeia de consulta do URI. Ela é formatada como uma cadeia de consulta de URI normal com pares de chave/valor; extraia os campos a seguir.
   * Para um convite aceito:
     1. `handle`
     2. `invitedXuid`
     3. `senderXuid`
   * Para uma entrada:
     1. `handle`
     2. `joinerXuid`
     3. `joineeXuid`

4. Inicie o código multijogador do título, que deve incluir uma chamada a [XblMultiplayerSetSubscriptionsEnabled](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersetsubscriptionsenabled.md).

5. Crie um objeto `XblMultiplayerSessionHandle` local chamando [XblMultiplayerSessionCreateHandle](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessioncreatehandle.md).

6. Chame [XblMultiplayerSessionJoin](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md) para entrar na sessão. Use as configurações de parâmetro a seguir para que a entrada seja definida como ativa.
   * `memberCustomConstantsJson` = `null`
   * `initializeRequested` = `false`
   * `joinWithActiveStatus` = `true`

7. Chame [XblMultiplayerSessionSetSessionChangeSubscription](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionsetsessionchangesubscription.md) para receber shoulder taps quando a sessão for alterada após a entrada.

8. Chame [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md) usando o identificador obtido conforme descrito na etapa 3. O usuário agora é membro da sessão e pode usar os dados da sessão para se conectar ao jogo.

[Voltar ao início deste tópico.](#top)

## Definir a atividade atual do usuário

A atividade atual do usuário é exibida nas experiências do usuário do painel do XBOX para o título. A atividade de um usuário pode ser definida por meio de uma sessão ou por meio da ativação do título. Neste último caso, o usuário entra em uma sessão por meio do matchmaking ou iniciando um jogo.

> [!NOTE]
>
> A atividade definida por meio de uma sessão pode ser excluída chamando [XblMultiplayerClearActivityAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerclearactivityasync.md).

Para definir uma sessão como a atividade atual do usuário, o título chama [XblMultiplayerSetActivityAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersetactivityasync.md), passando a referência da sessão.

Para definir a atividade atual do usuário por meio da ativação do título, veja [Entrar em uma sessão do MPSD a partir de uma ativação do título](#jamsfata) neste tópico.

[Voltar ao início deste tópico.](#top)

## Atualizar uma sessão do MPSD

> [!NOTE]
>
> Quando seu título atualiza uma sessão existente usando a API multijogador, lembre-se de que ele está trabalhando com uma cópia local até fazer uma chamada para gravar a sessão.

Para atualizar uma sessão existente, o título deve fazer o seguinte:

1. Fazer as alterações necessárias na sessão atual, por exemplo, chamando [XblMultiplayerSessionLeave](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionleave.md).

2. Quando todas as alterações forem feitas, gravar as alterações locais no MPSD usando qualquer um destes métodos.

   * [XblMultiplayerWriteSessionAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionasync.md)
   * [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)

   Defina o modo de gravação como [XblMultiplayerSessionWriteMode](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/enums/xblmultiplayersessionwritemode.md)`::SynchronizedUpdate` se estiver gravando em uma parte compartilhada que outros títulos também podem modificar. Para obter mais informações, veja a seção [Sincronização de atualizações de sessão](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md#synchronization-of-session-updates) no tópico Visão geral do Multiplayer Session Directory.

   O método de gravação grava a entrada no servidor e obtém a sessão mais recente, a partir da qual é possível descobrir os outros membros da sessão e os endereços seguros de dispositivo (SDAs) dos consoles deles. Para obter mais informações sobre como estabelecer uma conexão de rede entre esses consoles, veja Introdução ao Winsock no XBOX One.

3. Descartar o objeto de sessão local antigo. Usar o objeto de sessão recém-recuperado para que as ações futuras se baseiem no estado de sessão conhecido mais recente.

[Voltar ao início deste tópico.](#top)

## Sair de uma sessão do MPSD

Para permitir que um usuário saia de uma sessão, o título deve fazer o seguinte:

1. Chamar [XblMultiplayerSessionLeave](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionleave.md) para a sessão de jogo.

2. Atualizar a sessão de jogo no MPSD conforme descrito na seção [Atualizar uma sessão do MPSD](#update-an-mpsd-session) deste tópico.

3. Se necessário, chamar o método `XblMultiplayerSessionLeave` para a sessão de lobby e, em seguida, atualizar essa sessão.

4. Se necessário para a sessão de lobby, encerrar a API multijogador cancelando o registro com chamadas a [XblMultiplayerRemoveSubscriptionLostHandler](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerremovesubscriptionlosthandler.md) e [XblMultiplayerRemoveSessionChangedHandler](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerremovesessionchangedhandler.md).

O fluxograma a seguir mostra como sair da sessão e encerrar o multijogador.

![Imagem de um fluxograma que mostra como sair da sessão e encerrar o multijogador.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_Shut_Down.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=1b43ed2e21a28db2347eb8fd9f831aef)

[Voltar ao início deste tópico.](#top)

## Preencher vagas abertas na sessão durante o matchmaking

Para preencher as vagas abertas em uma sessão de tíquete durante o matchmaking, o título deve seguir etapas semelhantes às seguintes:

1. Acessar o estado de sessão mais recente da sessão de tíquete criada durante o matchmaking.

2. Adicionar os jogadores disponíveis para o jogo a partir da sessão de lobby.

3. Determinar se a sessão de tíquete está cheia.

4. Se a sessão estiver cheia, continuar o jogo.

5. Se a sessão ainda não estiver cheia, criar o tíquete de partida conforme descrito em [Criar um tíquete de partida](#camt) neste tópico. Certifique-se de criar o tíquete com o parâmetro `preserveSession` definido como `Always`.

6. Continuar com o matchmaking. Para obter mais informações, veja [Visão geral do matchmaking](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/matchmaking/live-matchmaking-overview.md).

O fluxograma a seguir mostra como preencher vagas abertas na sessão durante o matchmaking.

![Imagem de um fluxograma que mostra como preencher vagas abertas na sessão durante o matchmaking.](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/Multiplayer_2015_Fill_Open_Slots.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=536853a998a165affa7552a02f87d778)

[Voltar ao início deste tópico.](#top)

## Criar um tíquete de partida

Para criar um tíquete de partida, o batedor de matchmaking deve fazer o seguinte:

1. Chamar [XblMatchmakingCreateMatchTicketAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/matchmaking_c/functions/xblmatchmakingcreatematchticketasync.md), passando uma referência à sessão de tíquete. O método lê a sessão de tíquete do MPSD e inicia o matchmaking para os usuários da sessão. Internamente, o método chama `POST (/serviceconfigs/{scid}/hoppers/{hoppername})`.

2. Definir o parâmetro `preserveSession` como `Never` se o serviço de matchmaking for combinar os membros da sessão em uma nova sessão ou em outra sessão existente. Definir o parâmetro `preserveSession` como `Always` para permitir que o título reutilize uma sessão de jogo existente como sessão de tíquete para continuar o jogo. O serviço de matchmaking poderá então garantir que a sessão enviada seja preservada e que todos os jogadores combinados sejam adicionados a essa sessão.

3. Usar o [XblCreateMatchTicketResponse](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/matchmaking_c/structs/xblcreatematchticketresponse.md)`::EstimatedWaitTime` retornado no objeto `CreateMatchTicketResponse` para definir as expectativas dos usuários quanto ao tempo de matchmaking.

4. Usar o [XblCreateMatchTicketResponse](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/matchmaking_c/structs/xblcreatematchticketresponse.md)`::MatchTicketId` retornado no objeto de resposta para cancelar o matchmaking da sessão, se necessário, excluindo o tíquete. A exclusão do tíquete usa [XblMatchmakingDeleteMatchTicketAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/matchmaking_c/functions/xblmatchmakingdeletematchticketasync.md).

[Voltar ao início deste tópico.](#top)

## Obter o status do tíquete de partida

Seu título deve fazer o seguinte para recuperar o status do tíquete de partida.

1. Obter o objeto `XblMultiplayerSessionHandle` da sessão de tíquete.

2. Chamar [XblMultiplayerSessionMatchmakingServer](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionmatchmakingserver.md) para acessar o objeto [XblMultiplayerMatchmakingServer](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayermatchmakingserver.md) usado no matchmaking.

3. Verificar o objeto `XblMultiplayerMatchmakingServer` para determinar o status do processo de matchmaking, o tempo de espera típico da sessão e a referência da sessão de destino, caso uma partida tenha sido encontrada.


## Related topics

- [Visão geral do Multiplayer Session Directory](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md)
- [Código de exemplo do Multiplayer Session Directory (MPSD)](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-howto-nav.md)
- [Anular instância de tarefa](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/admin/scheduled-task/abort-task-instance.md)
- [Obter instâncias de tarefa](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/admin/scheduled-task/get-task-instances.md)
- [URIs de atividade multijogador](https://docs.xbox.com/pt-BR/reference/live/rest/uri/multiplayeractivity/atoc-reference-multiplayer-activity.md)