> ## 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.

# Recebendo convites

> Adicione o tratamento de convites para jogos multiplayer ao seu título dos serviços do XBOX registrando o protocolo multiplayer e os retornos de chamada de evento de convite do XGameActivation.

Use este tópico para adicionar convites de jogo ao seu título dos serviços do XBOX. Para receber convites multiplayer, seu jogo se registra no protocolo multiplayer e nos retornos de chamada de convite de jogo. Seu jogo recebe convites para o usuário local e, em seguida, adiciona esse usuário à sessão multiplayer.

## Pré-requisito

Para receber notificações de convite de jogo em um PC com Windows, instale a XBOX Game Bar. O aplicativo XBOX Game Bar é instalado por padrão no Windows 10, versão 1903 ou posterior do sistema operacional. Pressione **tecla Windows**+**G** para iniciar o aplicativo XBOX Game Bar e verificar se ele está instalado corretamente.

> [!NOTE]
>
> Se a XBOX Game Bar não estiver instalada no seu PC com Windows, você pode instalá-la pela [Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P).

## Registrando o protocolo multiplayer

Registrar o protocolo multiplayer informa ao sistema como iniciar seu jogo quando o usuário aceita um convite de jogo multiplayer. Para registrar o protocolo multiplayer, você precisa adicionar um elemento `MultiplayerProtocol` ao arquivo [MicrosoftGame.config](https://docs.xbox.com/pt-BR/build/core-features/common/game-config/MicrosoftGameConfig-toc.md), conforme mostrado no código a seguir.

```xml theme={null}
    <MultiplayerProtocol>true</MultiplayerProtocol>
```

Se você tiver vários executáveis no pacote, poderá especificar qual executável trata o protocolo multiplayer usando o atributo `Executable`, conforme mostrado no código a seguir.

```xml theme={null}
    <MultiplayerProtocol Executable="MyExecutableForMultiplayer.exe">true</MultiplayerProtocol>
```

## Registrando os retornos de chamada de convite de jogo multiplayer

> [!NOTE]
>
> As APIs `XGameInviteRegisterForEvent` e `XGameInviteUnregisterForEvent` foram preteridas. Em vez delas, use [XGameActivationRegisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) e [XGameActivationUnregisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md). Para obter orientações sobre a migração, consulte [XGameActivation](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/xgameactivation_members.md#remarks).

Para receber retornos de chamada de convite de jogo multiplayer, você deve se registrar para retornos de chamada de ativação usando a API [XGameActivationRegisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md), conforme mostrado no código a seguir.

Para obter mais informações sobre como registrar e cancelar o registro de retornos de chamada de ativação, consulte [XGameActivationRegisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) e [XGameActivationUnregisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md).

### API C simples

```cpp theme={null}
#include <XTaskQueue.h>
#include <XGameActivation.h>  
  
XTaskQueueHandle g_taskQueue;  
XTaskQueueRegistrationToken g_activationToken;  
  
void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)  
{  
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto handleId = inviteString.substr(pos + 7, 36);
            // Now call XblMultiplayerManagerJoinLobby
        }
    }
}  
  
void InitializeGame()  
{  
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);  
}  
  
void ShutdownGame()  
{  
    XGameActivationUnregisterForEvent(g_activationToken, true);  
}  
```

Para tratar corretamente o cenário de "convite aceito a partir de um estado suspenso", o título deve armazenar o `inviteUri` passado para o método manipulador `OnActivation()` no código de exemplo acima, proveniente do retorno de chamada de [XGameActivationRegisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md). Em seguida, o título deve aguardar a `RegisterAppStateChangeNotification`, que notifica quando o jogo foi totalmente retomado, antes de prosseguir com operações na sessão usando os detalhes fornecidos no `inviteUri`.

Para obter mais informações sobre `RegisterAppStateChangeNotification`, consulte [Ciclo de vida de jogos do XBOX (tópico sob NDA)](https://docs.xbox.com/pt-BR/build/console-features/console-workflows/xbox-game-life-cycle.md).

## Analisando o inviteUri de XGameActivationCallback

Quando seu jogo recebe o evento [XGameActivationCallback](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationcallback.md) com o tipo de ativação `AcceptedGameInvite`, você pode acessar a cadeia de caracteres `inviteUri` na estrutura [XGameActivationInfo](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/structs/xgameactivationinfo.md). O `inviteUri` está em um dos formatos a seguir.

### Para aceitar um convite de jogo

Quando o usuário aceita um convite de jogo, o jogo recebe o retorno de chamada de convite de jogo com um `inviteUri`, conforme mostrado no código a seguir.

```cpp theme={null}
    "ms-xbl-multiplayer://inviteHandleAccept?handle=%s&invitedXuid=%s&senderXuid=%s&context=%s"
    
    // for example:
    // "ms-xbl-multiplayer://inviteHandleAccept?handle=00000000-0000-1234-5678-1234567890ab&invitedXuid=1234567890123456&senderXuid=6543210987654321&context="
```

O URI sempre começa com "ms-xbl-multiplayer//", seguido dos identificadores a seguir.

* `inviteHandleAccept` indica que o retorno de chamada foi iniciado porque o usuário aceitou um convite de jogo.
* `handle` é o identificador de convite que você usa para ingressar na sessão multiplayer.
* `invitedXuid` é o ID do usuário dos serviços do XBOX que foi convidado para a sessão multiplayer.
* `senderXuid` é o ID do usuário dos serviços do XBOX que enviou o convite de jogo.
* `context` é o contexto adicional (opcional) que o remetente pode ter incluído.

### Para ingressar em uma sessão de jogo em andamento

Quando o usuário tenta ingressar em uma sessão multiplayer, o jogo recebe um retorno de chamada de convite com um `inviteUri`, conforme mostrado no código a seguir.

```cpp theme={null}
    "ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"
```

O URI sempre começa com "ms-xbl-multiplayer//", seguido dos identificadores a seguir.

* `activityHandleJoin` indica que o retorno de chamada foi iniciado porque o usuário aceitou um convite de jogo.
* `handle` é o identificador de atividade que você usa para ingressar na sessão multiplayer.
* `joinerXuid` é o ID do usuário dos serviços do XBOX que está tentando ingressar na sessão multiplayer.
* `joineeXuid` é o ID do usuário dos serviços do XBOX que está atualmente na sessão multiplayer.

## Ingressando em uma sessão de jogo multiplayer com handleId

### Usando o Multiplayer Manager

Se você estiver usando o Multiplayer Manager, poderá adicionar o usuário à sessão multiplayer usando a API [XblMultiplayerManagerJoinLobby](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md) e passando o `handleId` extraído do `inviteUri`. Você também pode usar o `xblUserHandle` para o `invitedXuid`, conforme mostrado no código a seguir.

#### API C simples

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);
```

### Usando a API Multiplayer diretamente

Se você estiver usando a API Multiplayer, siga as etapas a seguir para configurar sessões multiplayer e convites para o seu título.

1. Busque o documento da sessão multiplayer usando a API [XblMultiplayerGetSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md) e passe o `handleId` para ela.
2. Adicione o usuário local ao documento da sessão multiplayer usando a API [XblMultiplayerSessionJoin](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md).
3. Grave o documento da sessão multiplayer no serviço para confirmar essa alteração usando a API [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md).

## Documentação de referência da API

* [Xgameactivation (conteúdo da API)](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/xgameactivation_members.md)
  * Funções
    * [XGameActivationRegisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md)
    * [XGameActivationUnregisterForEvent](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md)
    * [XGameActivationCallback](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/functions/xgameactivationcallback.md)
  * Estruturas
    * [XGameActivationInfo](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/structs/xgameactivationinfo.md)
* [multiplayer\_manager\_c (conteúdo da API)](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members.md)
  * Funções
    * [XblMultiplayerManagerJoinLobby](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md)
    * [XblMultiplayerGetSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md)
    * [XblMultiplayerSessionJoin](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md)
    * [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)

## Confira também

[API XGameActivation](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/xgameactivation_members.md) [Tratando a ativação de protocolo para iniciar um jogo usando o Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation.md)


## Related topics

- [Código de exemplo do Multiplayer Activity](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [Código de exemplo de convites](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)
- [XGameActivation (conteúdo da API)](https://docs.xbox.com/pt-BR/reference/system/xgameactivation/xgameactivation_members.md)
- [XblMultiplayerGetSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md)
- [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)