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

# Visão geral do xCurl

> Visão geral do xCurl

Este artigo descreve a biblioteca `xCurl`, uma implementação das APIs da [libCurl](https://curl.haxx.se/libcurl/) em conformidade com o Microsoft Game Development Kit (GDK). O `xCurl` simplifica o desenvolvimento de títulos ao seguir todos os requisitos de segurança e as práticas recomendadas sem exigir nenhuma lógica ou tratamento especial do título. No entanto, ele não dá suporte à comunicação WebSocket. Se você precisar implementar a comunicação WebSocket, use a [libHttpClient](/pt-BR/build/console-features/networking/web-requests/http-networking#libhttpclient).

O `xCurl` difere da `libCurl` porque o `xCurl` é implementado com base no [WinHttp](/pt-BR/build/console-features/networking/web-requests/intro-winhttp) e segue automaticamente os requisitos e as práticas recomendadas do Microsoft Game Development Kit (GDK), incluindo o Gerenciamento do Tempo de Vida do Processo (PLM). Embora o `xCurl` seja compatível com a API da `libCurl`, a camada de transporte do `xCurl` usa exclusivamente o WinHttp e não utiliza a `libCurl`. Assim, o `xCurl` não precisa ser mantido sincronizado com a implementação de código aberto da `libCurl`, incluindo correções de bugs, números de versão e muito mais. Os desenvolvedores podem usar o `xCurl` para manter a mesma implementação HTTP da `libCurl` em todas as plataformas, alterando apenas uma inclusão de cabeçalho e a vinculação de biblioteca.

Várias APIs da `libCurl` não são implementadas no `xCurl` porque não são comumente usadas em cenários de desenvolvimento de jogos ou porque não têm uma funcionalidade equivalente no WinHttp para a qual possam ser mapeadas. As diferenças são descritas mais adiante neste artigo.

O `xCurl` depende do Gaming Runtime e não pode ser inicializado até que [XGameRuntimeInitialize](/pt-BR/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) seja chamada.

Para entender como os métodos do `xCurl` funcionam, consulte a documentação da [API da libCurl](https://curl.haxx.se/libcurl/c/).

<Note>As implementações do `xCurl` e do `WinHttp` funcionam tanto no PC com Windows quanto no console XBOX, sem necessidade de alterações de código.</Note>

## Suporte ao desenvolvedor

O `xCurl` é baseado no WinHttp, não na `libCurl`, e faz parte do Microsoft Game Development Kit (GDK).

As solicitações de suporte devem ser enviadas pelos canais de suporte recomendados para títulos do Microsoft Game Development Kit (GDK), como entrar em contato com seu representante da Microsoft ou com a equipe de suporte ao desenvolvedor por meio dos Fóruns de Desenvolvedores XBOX.

## Adicionar o xCurl ao seu projeto

Para usar o `xCurl` em um jogo do Microsoft Game Development Kit (GDK) em um PC com Windows 10 ou em um console XBOX, inclua os cabeçalhos e as bibliotecas do SDK de extensão do `xCurl` no seu projeto.

1. Certifique-se de instalar o Gaming Runtime Development Kit (GRDK) no seu PC de desenvolvimento.
2. Abra o arquivo .vcxproj do seu jogo e adicione o elemento a seguir. Isso vincula a biblioteca de importação e inclui o *xCurl.dll* na saída do build.

```xml theme={null}
    <GDKExtLibNames>Xbox.xCurl.API</GDKExtLibNames>
```

1. O `xCurl` tem um cabeçalho diferente para se diferenciar da `libCurl`. Nos locais em que *curl.h* seria incluído no seu jogo, substitua o cabeçalho por *xCurl.h*, conforme mostrado a seguir.

```cpp theme={null}
    #include <xCurl.h>
```

## Configuração

O `xCurl` é equivalente à `libCurl` compilada com os seguintes sinalizadores de build.

* HTTP\_ONLY
* CURL\_NO\_OLDIES
* CURL\_DISABLE\_PROXY
* CURL\_DISABLE\_COOKIES
* CURL\_DISABLE\_DOH
* CURL\_DISABLE\_PROGRESS\_METER
* CURL\_DISABLE\_MIME
* USE\_SCHANNEL

## Inicialização da rede

O `xCurl` trata a inicialização da rede automaticamente. Você pode configurar e realizar solicitações em qualquer ponto do ciclo de vida do seu título. Todas as solicitações iniciadas antes da inicialização da rede são adiadas e enfileiradas até que a rede seja inicializada. O xCurl garante que suas solicitações sejam feitas na primeira oportunidade possível, sem nenhum tratamento extra exigido pelo seu título.

## Suspensão/retomada do título

O `xCurl` trata a suspensão e a retomada automaticamente. Na suspensão, todas as solicitações pendentes são canceladas imediatamente e falham com `CURLE_NO_CONNECTION_AVAILABLE`. Além disso, consultar `curl_easy_getinfo` para `CURLINFO_OS_ERRNO` nessas solicitações retorna `HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME)`, assim como qualquer outra API GRTS, caso você queira tratar essas falhas de forma diferente das falhas gerais de desconexão de rede.

Todos os identificadores do `xCurl` permanecem válidos durante todo o ciclo de vida do título, inclusive entre suspensões e retomadas. Não é necessário limpar nem inicializar nenhum identificador do `xCurl` na suspensão/retomada. Todas as novas solicitações iniciadas após a suspensão são adiadas até a retomada e a subsequente inicialização da rede. Esse atraso garante que elas comecem o mais rápido possível, sem exigir nenhum tratamento extra do seu título.

<Note>Quando o seu título usa a interface multi do `xCurl`, ele deve continuar a chamar `curl_multi_perform`, juntamente com, opcionalmente, `curl_multi_poll` ou `curl_multi_wait`, na suspensão enquanto houver solicitações pendentes. O `xCurl` bloqueia a suspensão até que todas as solicitações em andamento sejam concluídas, e deixar de chamar `curl_multi_perform` pode fazer com que o tempo limite do seu título se esgote durante a suspensão. Recomendamos continuar a chamar curl\_multi\_perform durante todo o ciclo de vida, independentemente do estado de suspensão/retomada. O `xCurl` trata internamente todas as complexidades do estado suspenso.</Note>

## Funcionalidade de segurança

Todas as solicitações HTTPS feitas por meio do `xCurl` seguem as [práticas recomendadas de segurança da comunicação (artigo sob NDA)](/pt-BR/build/game-principles/security/communication-security-overview). O `xCurl` impõe automaticamente qualquer fixação de certificado especial especificada por meio do "Portal de Logon Único" do seu título. Não há suporte para o uso de `CURLOPT_SSL_VERIFYPEER` para desabilitar a validação de certificados.

Em kits de desenvolvimento, você pode especificar o esquema HTTP não criptografado, `http://`, para tráfego de depuração e fins de teste. Para todas as solicitações RETAIL, você deve especificar o esquema HTTPS, `https://`, para fornecer o nível de proteção recomendado. As solicitações do xCurl que não especificam explicitamente um esquema inferem o esquema HTTPS.

<Note>O `xCurl` não realiza a inserção automática de tokens. Para recuperar os tokens do XBOX Live, seu título deve chamar as APIs GRTS `XUserGetTokenAndSignatureAsync` ou `XUserGetTokenAndSignatureUtf16Async` para recuperar os cabeçalhos de autorização e assinatura e, em seguida, usar as opções `CURLOPT_HEADER`, `CURLOPT_HTTPHEADER` ou `CURLOPT_HEADERFUNCTION` em uma chamada a `curl_easy_setopt` para definir os cabeçalhos antes de fazer a solicitação.</Note>

## Considerações sobre memória e simultaneidade

O `xCurl` compartilha as mesmas limitações de solicitações simultâneas que se aplicam ao `WinHttp`. Os títulos devem limitar as solicitações simultâneas a oito ou menos para garantir que todas as chamadas funcionem corretamente. Esse limite de simultaneidade se aplica às solicitações simultâneas emitidas por qualquer um entre `xCurl`, `WinHttp` e as APIs dos serviços XBOX.

O `xCurl` usa um buffer duplo alternado para receber dados. Esse padrão permite que ele forneça maior taxa de transferência ao preencher um segundo buffer enquanto o título lê o primeiro. No entanto, se o retorno de chamada de leitura demorar muito ou se `curl_multi_perform` não for chamada com frequência suficiente no modo multi, a memória do kernel do WinSock poderá se acumular. Para obter mais informações sobre a memória do kernel do WinSock, consulte [considerações sobre memória de soquete](/pt-BR/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory).

### Controlar as alocações do xCurl

Por padrão, o `xCurl` usa o heap do Windows, e suas alocações podem ser rastreadas por meio de `XMemSetWin32HeapTrackingHooks`. Como alternativa, as funções de memória podem ser fornecidas no momento da inicialização, como na `libCurl`.

Além de [curl\_global\_init\_mem](https://curl.haxx.se/libcurl/c/curl_global_init_mem.html), o `xCurl` fornece a função opcional [xCurl\_global\_init\_mem](/pt-BR/reference/networking/xcurl/functions/xcurl_global_init_mem). Os retornos de chamada fornecidos a essa versão de `init` são semelhantes a outros retornos de chamada de memória do Microsoft Game Development Kit (GDK) e fornecem mais informações do que os retornos de chamada padrão da `libCurl` sobre os dados que estão sendo alocados.

## Opções com suporte

As opções a seguir têm suporte com identificadores `easy` no `xCurl`.

* CURLOPT\_VERBOSE
* CURLOPT\_HEADER
* CURLOPT\_NOBODY
* CURLOPT\_FAILONERROR
* CURLOPT\_UPLOAD
* CURLOPT\_PUT
* CURLOPT\_ACCEPT\_ENCODING
* CURLOPT\_TRANSFER\_ENCODING
* CURLOPT\_FOLLOWLOCATION
* CURLOPT\_MAXREDIRS
* CURLOPT\_POST
* CURLOPT\_COPYPOSTFIELDS
* CURLOPT\_POSTFIELDS
* CURLOPT\_POSTFIELDSIZE
* CURLOPT\_POSTFIELDSIZE\_LARGE
* CURLOPT\_POSTREDIR
* CURLOPT\_REFERER
* CURLOPT\_USERAGENT
* CURLOPT\_HTTPHEADER
* CURLOPT\_HTTPGET
* CURLOPT\_HTTP\_VERSION
* CURLOPT\_CUSTOMREQUEST
* CURLOPT\_HEADERDATA
* CURLOPT\_ERRORBUFFER
* CURLOPT\_WRITEDATA
* CURLOPT\_READDATA
* CURLOPT\_INFILESIZE
* CURLOPT\_INFILESIZE\_LARGE
* CURLOPT\_CURLU
* CURLOPT\_URL
* CURLOPT\_PORT
* CURLOPT\_TIMEOUT
* CURLOPT\_TIMEOUT\_MS
* CURLOPT\_CONNECTTIMEOUT
* CURLOPT\_CONNECTTIMEOUT\_MS
* CURLOPT\_DEBUGFUNCTION
* CURLOPT\_DEBUGDATA
* CURLOPT\_HEADERFUNCTION
* CURLOPT\_WRITEFUNCTION
* CURLOPT\_READFUNCTION
* CURLOPT\_SSL\_VERIFYPEER
* CURLOPT\_SSL\_VERIFYHOST
* CURLOPT\_SSLCERT
* CURLOPT\_BUFFERSIZE
* CURLOPT\_UPLOAD\_BUFFERSIZE
* CURLOPT\_PRIVATE
* CURLOPT\_IGNORE\_CONTENT\_LENGTH
* CURLOPT\_HTTP\_TRANSFER\_DECODING
* CURLOPT\_HTTP\_CONTENT\_DECODING

## Funcionalidade sem suporte

### Soquetes e fd\_set

O `xCurl` não expõe o soquete subjacente usado para o transporte. Portanto, o `xCurl` não implementa nenhuma opção ou API que seria usada para operações de soquete. Essa limitação também remove a capacidade de usar `fd_sets` para aguardar a chegada de dados por meio de `select` e `poll`. Para aguardar a chegada de trabalho, use `curl_multi_wait` e `curl_multi_poll`.

As APIs a seguir não estão presentes no `xCurl`

* `curl_easy_send`
* `curl_easy_recv`
* `curl_multi_socket`
* `curl_multi_socket_action`
* `curl_multi_socket_all`
* `curl_multi_assign`
* `curl_multi_fdset`

As opções a seguir não têm efeito e retornam o erro `CURLE_NOT_BUILT_IN`.

* CURLOPT\_LOCALPORT
* CURLOPT\_CONNECT\_ONLY
* CURLOPT\_SOCKOPTFUNCTION
* CURLOPT\_SOCKOPTDATA
* CURLOPT\_OPENSOCKETFUNCTION
* CURLOPT\_OPENSOCKETDATA
* CURLOPT\_CLOSESOCKETFUNCTION
* CURLOPT\_CLOSESOCKETDATA
* CURLOPT\_XOAUTH2\_BEARER
* CURLOPT\_PROGRESSFUNCTION
* CURLOPT\_PROGRESSDATA
* CURLOPT\_XFERINFOFUNCTION
* CURLOPT\_XFERINFODATA
* CURLOPT\_NOPROGRESS
* CURLINFO\_LASTSOCKET
* CURLINFO\_ACTIVESOCKET
* CURLMOPT\_SOCKETFUNCTION
* CURLMOPT\_SOCKETDATA
* CURLMOPT\_PIPELINING
* CURLMOPT\_PUSHFUNCTION

### CURL Share

A interface `Share` do `CURL` não é implementada.

### Pausar e retomar transferências

Atualmente, esse recurso não tem suporte. Retornar CURL\_WRITEFUNC\_PAUSE ou CURL\_READFUNC\_PAUSE de um retorno de chamada resulta em uma operação anulada que não pode ser retomada.

## Confira também

[API da libCurl](https://curl.haxx.se/libcurl/c/)

[Configurar serviços Web no Partner Center (artigo sob NDA)](/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services)

[Fiddler em consoles XBOX One](/pt-BR/build/console-features/networking/tools/fiddler-setup-networking)

[Visão geral das práticas recomendadas de segurança da comunicação (artigo sob NDA)](/pt-BR/build/game-principles/security/communication-security-overview)


## Related topics

- [Visão geral do Unity](/pt-BR/paths/unity/overview.md)
- [Visão geral do Unreal Engine](/pt-BR/paths/unreal/overview.md)
- [Visão geral do XBOX Series X|S](/pt-BR/paths/series-xs/overview.md)
- [Visão geral do Windows & ROG XBOX Ally](/pt-BR/paths/windows/overview.md)
- [Visão geral do Play Anywhere (Console + PC)](/pt-BR/paths/play-anywhere/overview.md)