xCurl, uma implementação das APIs da 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.
O xCurl difere da libCurl porque o xCurl é implementado com base no 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 seja chamada.
Para entender como os métodos do xCurl funcionam, consulte a documentação da API da libCurl.
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.Suporte ao desenvolvedor
OxCurl é 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 oxCurl 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.
- Certifique-se de instalar o Gaming Runtime Development Kit (GRDK) no seu PC de desenvolvimento.
- 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.
- O
xCurltem um cabeçalho diferente para se diferenciar dalibCurl. Nos locais em que curl.h seria incluído no seu jogo, substitua o cabeçalho por xCurl.h, conforme mostrado a seguir.
Configuração
OxCurl é 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
OxCurl 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
OxCurl 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.
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.Funcionalidade de segurança
Todas as solicitações HTTPS feitas por meio doxCurl seguem as práticas recomendadas de segurança da comunicação (artigo sob NDA). 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.
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.Considerações sobre memória e simultaneidade
OxCurl 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.
Controlar as alocações do xCurl
Por padrão, oxCurl 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, o xCurl fornece a função opcional 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 identificadoreseasy 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
OxCurl 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_sendcurl_easy_recvcurl_multi_socketcurl_multi_socket_actioncurl_multi_socket_allcurl_multi_assigncurl_multi_fdset
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 interfaceShare do CURL não é implementada.