Função WinHttpOpenRequest (winhttp.h)

Artigo
08/27/2023

A função WinHttpOpenRequest cria um identificador de solicitação HTTP.

Sintaxe

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Parâmetros

[in] hConnect

Identificador de conexão HINTERNET para uma sessão HTTP retornada por WinHttpConnect.

[in] pwszVerb

Ponteiro para uma cadeia de caracteres que contém o verbo HTTP a ser usado na solicitação. Se esse parâmetro for NULL, a função usará GET como o verbo HTTP. Nota Essa cadeia de caracteres deve ser toda maiúscula. Muitos servidores tratam os verbos HTTP como diferenciadores de maiúsculas e minúsculas e as RFCs (Solicitações de Comentários) da IETF (Internet Engineering Task Force) soletram esses verbos usando apenas caracteres maiúsculos.

[in] pwszObjectName

Ponteiro para uma cadeia de caracteres que contém o nome do recurso de destino do verbo HTTP especificado. Geralmente, esse é um nome de arquivo, um módulo executável ou um especificador de pesquisa.

[in] pwszVersion

Ponteiro para uma cadeia de caracteres que contém a versão HTTP. Se esse parâmetro for NULL, a função usará HTTP/1.1.

[in] pwszReferrer

Ponteiro para uma cadeia de caracteres que especifica a URL do documento do qual a URL na solicitação pwszObjectName foi obtida. Se esse parâmetro for definido como WINHTTP_NO_REFERER, nenhum documento de referência será especificado.

[in] ppwszAcceptTypes

Ponteiro para uma matriz terminada em nulo de ponteiros de cadeia de caracteres que especifica os tipos de mídia aceitos pelo cliente. Se esse parâmetro for definido como WINHTTP_DEFAULT_ACCEPT_TYPES, nenhum tipo será aceito pelo cliente. Normalmente, os servidores lidam com a falta de tipos aceitos como indicação de que o cliente aceita apenas documentos do tipo "text/*"; ou seja, somente documentos de texto— sem imagens ou outros arquivos binários. Para obter uma lista de tipos de mídia válidos, consulte Tipos de mídia definidos pela IANA em http://www.iana.org/assignments/media-types/.

[in] dwFlags

Valor inteiro longo sem sinal que contém os valores do sinalizador da Internet. Esse valor pode ser um ou mais dos seguintes:

Valor	Significado
WINHTTP_FLAG_BYPASS_PROXY_CACHE	Esse sinalizador fornece o mesmo comportamento que WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE	Caracteres não seguros na URL passada para pwszObjectName não são convertidos em sequências de escape.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY	Caracteres não seguros no componente de consulta da URL passada para pwszObjectName não são convertidos em sequências de escape.
WINHTTP_FLAG_ESCAPE_PERCENT	A cadeia de caracteres passada para pwszObjectName é convertida de um LPCWSTR em um LPSTR. Todos os caracteres não seguros são convertidos em uma sequência de escape, incluindo o símbolo de porcentagem. Por padrão, todos os caracteres não seguros, exceto o símbolo de porcentagem, são convertidos em uma sequência de escape.
WINHTTP_FLAG_NULL_CODEPAGE	Supõe-se que a cadeia de caracteres passada para pwszObjectName consista em caracteres ANSI válidos representados pelo WCHAR. Nenhuma marcar é feita para caracteres não seguros. Windows 7: Essa opção está obsoleta.
WINHTTP_FLAG_REFRESH	Indica que a solicitação deve ser encaminhada para o servidor de origem em vez de enviar uma versão armazenada em cache de um recurso de um servidor proxy. Quando esse sinalizador é usado, um cabeçalho "Pragma: no-cache" é adicionado ao identificador de solicitação. Ao criar um cabeçalho de solicitação HTTP/1.1, um "Cache-Control: no-cache" também é adicionado.
WINHTTP_FLAG_SECURE	Usa semântica de transação segura. Isso se traduz no uso do protocolo SSL/protocolo TLS.

Retornar valor

Retornará um identificador de solicitação HTTP válido se tiver êxito ou NULL , caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Código do Erro	Descrição
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	O tipo de identificador fornecido está incorreto para esta operação.
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
ERROR_WINHTTP_INVALID_URL	A URL é inválida.
ERROR_WINHTTP_OPERATION_CANCELLED	A operação foi cancelada, geralmente porque o identificador no qual a solicitação estava operando foi fechado antes da conclusão da operação.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	A URL especificou um esquema diferente de "http:" ou "https:".
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows)

Comentários

O valor retornado indica êxito ou falha. Para obter informações de erro estendidas, chame GetLastError.

A função WinHttpOpenRequest cria um novo identificador de solicitação HTTP e armazena os parâmetros especificados nesse identificador. Um identificador de solicitação HTTP contém uma solicitação para enviar a um servidor HTTP e contém todos os cabeçalhos RFC822/MIME/HTTP a serem enviados como parte da solicitação.

Se pwszVerb estiver definido como "HEAD", o cabeçalho Content-Length será ignorado.

Se uma função de retorno de chamada status tiver sido instalada com WinHttpSetStatusCallback, uma notificação de WINHTTP_CALLBACK_STATUS_HANDLE_CREATED indicará que WinHttpOpenRequest criou um identificador de solicitação.

Depois que o aplicativo de chamada terminar de usar o identificador HINTERNET retornado por WinHttpOpenRequest, ele deverá ser fechado usando a função WinHttpCloseHandle .

Nota Para Windows XP e Windows 2000, consulte a seção Requisitos de tempo de execução da página inicial do WinHttp.

Exemplos

Este exemplo mostra como obter um identificador HINTERNET , abrir uma sessão HTTP, criar um cabeçalho de solicitação e enviar esse cabeçalho para o servidor.


    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/1.0", 
                             WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                             WINHTTP_NO_PROXY_NAME, 
                             WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES,
                                       0);

    // Send a Request.
    if (hRequest) 
        bResults = WinHttpSendRequest( hRequest, 
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       0, 0);

    // PLACE ADDITIONAL CODE HERE.

    // Report any errors.
    if (!bResults)
        printf( "Error %d has occurred.\n", GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winhttp.h
Biblioteca	Winhttp.lib
DLL	Winhttp.dll
Redistribuível	WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.