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

# MsQuic

> MsQuic

Este artigo descreve como usar o [MsQuic](https://github.com/microsoft/msquic) com o Microsoft Game Development Kit (GDK). O MsQuic é uma implementação da Microsoft do protocolo [IETF QUIC](https://datatracker.ietf.org/wg/quic/about/). Ele é multiplataforma, escrito em C e projetado para ser uma biblioteca QUIC de uso geral.

O QUIC foi originalmente projetado para substituir cenários que usam "TLS sobre TCP", como o HTTP. Os desenvolvedores o expandiram para uma camada de transporte de dados UDP de uso geral, adequada para multiplexar mensagens de datagrama não confiáveis em tempo real e fluxos confiáveis semelhantes ao TCP em uma única conexão. Esse design o torna especialmente atraente como camada de transporte cliente/servidor e como base para fluxos de dados de tráfego de jogos em tempo real.

O MsQuic é adaptado para títulos do GDK e também está disponível para várias plataformas, incluindo Windows Server, Linux para desktop e servidor, iOS, Android e macOS.

A [documentação da API do MsQuic](https://github.com/microsoft/msquic/blob/main/docs/API.md) aborda muitos conceitos importantes do MsQuic e mostra como programar usando a superfície da API do MsQuic.

## Recursos do QUIC

* Todos os pacotes são criptografados e o handshake é autenticado usando TLS 1.3.
* Fluxos paralelos de dados de aplicativo confiáveis e não confiáveis.
* Troca de dados de aplicativo na primeira viagem de ida e volta (0-RTT).
* Controle de congestionamento e recuperação de perdas aprimorados.
* Resistência a uma alteração no endereço IP ou na porta do cliente.
* Balanceamento de carga sem estado.
* Facilmente extensível para novos recursos e extensões.

## Implementação do MsQuic

Além de ser adaptado para uso com títulos do GDK, o MsQuic tem vários recursos que o diferenciam de outras implementações do QUIC:

* Otimizado para cliente e servidor.
* Otimizado para máxima taxa de transferência e mínima latência.
* E/S assíncrona.
* Suporte a RSS (Receive Side Scaling).
* Suporte ao agrupamento de envios e recebimentos UDP.

O MsQuic implementa as seguintes RFCs do QUIC:

* [RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000)
* [RFC 9001](https://datatracker.ietf.org/doc/html/rfc9001)
* [RFC 9002](https://datatracker.ietf.org/doc/html/rfc9002)

O MsQuic implementa as seguintes extensões de rascunho do QUIC:

* [Datagram](https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagram)
* [Version Negotiation](https://datatracker.ietf.org/doc/html/draft-ietf-quic-version-negotiation)
* [Load Balancing](https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers)
* [ACK Frequency](https://datatracker.ietf.org/doc/html/draft-ietf-quic-ack-frequency)
* [Perf Testing](https://datatracker.ietf.org/doc/html/draft-banks-quic-performance)

## Como obter o MsQuic

A Microsoft hospeda o MsQuic em um repositório de código aberto no GitHub. Você deve obter o MsQuic por meio de uma de suas versões oficiais, localizadas [aqui](https://github.com/microsoft/msquic/blob/main/docs/Release.md). O suporte ao console XBOX Series X|S foi adicionado na versão prerelease/1.9, mas recomendamos que você use a versão oficial mais recente sempre que possível para títulos do GDK.

Você pode encontrar binários pré-compilados do MsQuic para uma determinada versão na seção [Assets](https://github.com/microsoft/msquic/releases) dessa versão. Todos os tipos de build de uma determinada versão do MsQuic são totalmente compatíveis entre si. Embora o MsQuic também tente manter a compatibilidade com versões anteriores, consulte a documentação e as notas de versão do MsQuic para conhecer as expectativas de compatibilidade entre diferentes versões.

### Títulos de PC baseados no GDK

Use o binário pré-compilado `msquic_windows_x64_Release_openssl` para títulos de PC baseados no GDK.

Os títulos do GDK no PC são executados como aplicativos Win32 x64 nativos. Use a versão do MsQuic compilada para a plataforma x64. No PC, use a versão do MsQuic compilada com OpenSSL, pois ela dá suporte a todas as versões do sistema operacional compatíveis com o GDK. A versão que usa Schannel só dá suporte ao Windows 11 e posteriores.

### Títulos de console baseados no GDK

Use o binário pré-compilado `msquic_gamecore_console_x64_Release_schannel` para títulos de console baseados no GDK.

O MsQuic fornece um tipo de build especial para títulos baseados no GDK em consoles XBOX. Esse tipo restringe o MsQuic às APIs em `WINAPI_PARTITION_GAMES` e faz com que o MsQuic seja vinculado a `XGamePlatform.lib`. Para consumir esse tipo de build, você deve instalar o XGDK da versão de outubro de 2021 ou posterior. O MsQuic usa Schannel ao compilar para títulos de console baseados no GDK.

<a id="ClientServerAuthentication" />

## Autenticação de cliente e servidor

O MsQuic utiliza automaticamente os mesmos caminhos de autenticação e verificação usados em solicitações da Web HTTPS para autenticar seu servidor. A autenticação do cliente deve seguir as práticas recomendadas descritas em [práticas recomendadas para comunicação segura entre cliente/servidor (tópico sob NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication).

No MsQuic, tanto no cliente quanto no servidor, você deve usar a API [ConfigurationLoadCredential](https://github.com/microsoft/msquic/blob/main/docs/api/ConfigurationLoadCredential.md) com um [QUIC\_CREDENTIAL\_CONFIG](https://github.com/microsoft/msquic/blob/main/docs/api/QUIC_CREDENTIAL_CONFIG.md) apropriado para configurar seus certificados. Todos os conjuntos de criptografia incluídos por padrão no MsQuic são considerados seguros, mas é importante configurar corretamente a forma como o MsQuic valida os certificados no cliente e no servidor para garantir que um canal de comunicação seguro e autenticado seja estabelecido.

No servidor, para usar a autenticação de cliente com token XSTS, você deve especificar os sinalizadores `QUIC_CREDENTIAL_FLAG_REQUIRE_CLIENT_AUTHENTICATION`, `QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED` e `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`. Ao especificar o sinalizador `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`, você mesmo deve validar o certificado do cliente no retorno de chamada do evento [QUIC\_CONNECTION\_EVENT\_PEER\_CERTIFICATE\_RECEIVED](https://github.com/microsoft/msquic/blob/main/docs/api/QUIC_CONNECTION_EVENT.md#quic_connection_event_peer_certificate_received), conforme descrito na seção [práticas recomendadas para comunicação segura entre cliente/servidor (tópico sob NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication).

Além disso, no servidor, você deve fornecer um certificado com raiz adequada para permitir que o cliente autentique seu servidor, assim como faria em um servidor Web HTTPS.

No cliente, você *nunca* deve especificar o sinalizador `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`, pois o comportamento padrão do MsQuic para autenticação do servidor é a maneira mais fácil e segura de validar a identidade. Em vez disso, para a autenticação de cliente com token XSTS, você deve especificar o sinalizador `QUIC_CREDENTIAL_FLAG_CLIENT` junto com o certificado gerado pelo seu servidor, conforme descrito na seção [práticas recomendadas para comunicação segura entre cliente/servidor (tópico sob NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication). Recomendamos fornecer o certificado do cliente especificando o modo `QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT` e usando APIs como [CertCreateContext](https://learn.microsoft.com/windows/win32/api/wincrypt/nf-wincrypt-certcreatecontext) para gerar o contexto diretamente a partir dos dados de resposta da sua solicitação da Web.

## Inicialização da rede

O MsQuic não lida automaticamente com a [inicialização da rede](/pt-BR/build/console-features/networking/initialization-connectivity-networking) para títulos do GDK. Aguarde a inicialização da rede depois que o título for iniciado e após cada retomada antes de inicializar o MsQuic usando [MsQuicOpenVersion](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpenVersion.md) ou [MsQuicOpen](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpen.md).

<a id="SuspendResume" />

## Suspensão e retomada

Registre-se para receber eventos de suspensão e retomada usando `RegisterAppStateChangeNotification`. Na suspensão, feche todos os fluxos abertos e feche o MsQuic. Em seguida, na retomada, aguarde a inicialização da rede e reabra o MsQuic.

Para fechar todos os fluxos do MsQuic rapidamente dentro do tempo limite de suspensão, para cada fluxo aberto, chame [StreamShutdown](https://github.com/microsoft/msquic/blob/main/docs/api/StreamShutdown.md) com os sinalizadores `QUIC_STREAM_SHUTDOWN_FLAG_ABORT` e `QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE`. Essa chamada dispara imediatamente um evento `QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE`. Nesse ponto, é seguro chamar [StreamClose](https://github.com/microsoft/msquic/blob/main/docs/api/StreamClose.md) para fechar o fluxo. Depois que todos os fluxos de uma determinada conexão forem fechados, chame [ConnectionShutdown](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionShutdown.md) com o sinalizador `QUIC_CONNECTION_SHUTDOWN_FLAG_SILENT`, seguido de [ConnectionClose](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionClose.md). Depois de fechar todas as conexões, chame [RegistrationClose](https://github.com/microsoft/msquic/blob/main/docs/api/RegistrationClose.md) e [ConfigurationClose](https://github.com/microsoft/msquic/blob/main/docs/api/ConfigurationClose.md) para quaisquer registros e configurações pendentes, seguido de [MsQuicClose](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicClose.md).

## Porta preferencial

Use a [porta multijogador UDP local preferencial](/pt-BR/build/console-features/networking/game-mesh/preferred-local-udp-multiplayer-port-networking) para o tráfego principal do jogo em títulos do GDK. Defina essa porta no MsQuic usando a função [SetParam](https://github.com/microsoft/msquic/blob/main/docs/api/SetParam.md) com a configuração `QUIC_PARAM_CONN_LOCAL_ADDRESS` em um identificador de objeto de conexão antes de chamar [ConnectionStart](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionStart.md).

Ao definir `QUIC_PARAM_CONN_LOCAL_ADDRESS`, especifique a família `AF_UNSPEC` para permitir soquetes de pilha dupla IPv4 e IPv6. O exemplo a seguir mostra como definir a porta preferencial quando `MsQuicCallTable` é retornado de [MsQuicOpen](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpen.md) e `MsQuicConnectionHandle` é retornado de [ConnectionOpen](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionOpen.md).

```text theme={null}
uint16_t preferredPort;
if (SUCCEEDED(XNetworkingQueryPreferredLocalUdpMultiplayerPort(&preferredPort)))
{
    QUIC_ADDR localAddress = {};
    localAddress.si_family = AF_UNSPEC;
    localAddress.Ipv4.sin_port = htons(preferredPort);

    QUIC_STATUS status = MsQuicCallTable->SetParam(
        MsQuicConnectionHandle,
        QUIC_PARAM_LEVEL_CONNECTION,
        QUIC_PARAM_CONN_LOCAL_ADDRESS,
        sizeof(localAddress),
        &localAddress);
}
```

## Considerações sobre memória

A implementação de alto desempenho do MsQuic permite que grandes larguras de banda sejam transferidas de e para seu título do GDK. Como uma extensão das [Considerações sobre memória do WinSock](/pt-BR/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory), ao usar o MsQuic, siga estas práticas recomendadas para minimizar o consumo de memória pelo kernel:

Os títulos do GDK devem manter qualquer tempo de execução no retorno de chamada no mínimo. O MsQuic não usa threads separados para a execução do protocolo e as chamadas ascendentes para o aplicativo. Portanto, qualquer atraso significativo no retorno de chamada atrasará o protocolo e aumentará o consumo de memória exigido pelo kernel. Qualquer tempo ou trabalho significativo que precise ser concluído pelo título deve acontecer em seu próprio thread.

Os títulos do GDK devem gerenciar seus buffers de envio com eficiência para reduzir o uso de memória do kernel. Para obter mais informações, confira [Buffer de envio no MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Streams.md#send-buffering) para saber como o MsQuic permite que seu título controle esse comportamento.

É altamente recomendável usar recebimentos assíncronos com o MsQuic para garantir que todos os dados recebidos sejam transferidos para buffers do modo de usuário com eficiência. [Recebimento no MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Streams.md#receiving) tem detalhes adicionais sobre como lidar com recebimentos assíncronos. Além disso, não use o recurso de aceitação parcial de dados em clientes GDK do MsQuic, para minimizar a quantidade de memória do kernel consumida.

## Confira também

[MsQuic](https://github.com/microsoft/msquic)

[Documentação da API do MsQuic](https://github.com/microsoft/msquic/blob/main/docs/API.md)

[Versões do MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Release.md)

[Documentação de build do MsQuic](https://github.com/microsoft/msquic/blob/main/docs/BUILD.md)

[Exemplo de servidor PlayFab MsQuic Echo](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Live/MsQuicEcho)


## Related topics

- [MsQuic](/build/console-features/networking/game-mesh/msquic-intro-networking.md)
- [Game Mesh](/build/console-features/networking/game-mesh/game-mesh-toc.md)
- [Networking on XBOX consoles with the GDK](/build/console-features/networking/index.md)
- [Game mesh networking for XBOX titles](/build/console-features/networking/game-mesh/index.md)
- [XBOX 游戏的 Game mesh 网络](/zh-CN/build/console-features/networking/game-mesh/index.md)