Função WinHttpCreateUrl (winhttp.h)

A função WinHttpCreateUrl cria uma URL de partes do componente, como o nome e o caminho do host.

Sintaxe

WINHTTPAPI BOOL WinHttpCreateUrl(
  [in]      LPURL_COMPONENTS lpUrlComponents,
  [in]      DWORD            dwFlags,
  [out]     LPWSTR           pwszUrl,
  [in, out] LPDWORD          pdwUrlLength
);

Parâmetros

[in] lpUrlComponents

Ponteiro para uma estrutura URL_COMPONENTS que contém os componentes dos quais criar a URL.

[in] dwFlags

Sinalizadores que controlam a operação dessa função. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
ICU_ESCAPE	Converte todos os caracteres não seguros em suas sequências de escape correspondentes na cadeia de caracteres de caminho apontada pelo membro lpszUrlPath e em lpszExtraInfo a cadeia de caracteres de informações extras apontada pelo membro da estrutura URL_COMPONENTS apontada pelo parâmetro lpUrlComponents .
ICU_REJECT_USERPWD	Rejeita URLs como entrada que contém um nome de usuário, uma senha ou ambos. Se a função falhar devido a uma URL inválida, as chamadas subsequentes para GetLastError retornarão ERROR_WINHTTP_INVALID_URL.

[out] pwszUrl

Ponteiro para um buffer de caracteres que recebe a URL como uma cadeia de caracteres largos (Unicode).

[in, out] pdwUrlLength

Ponteiro para uma variável do tipo inteiro longo sem sinal que recebe o comprimento do buffer pwszUrl em caracteres largos (Unicode). Quando a função retorna, esse parâmetro recebe o comprimento da cadeia de caracteres de URL larga em caracteres, menos 1 para o caractere de terminação. Se GetLastError retornar ERROR_INSUFFICIENT_BUFFER, esse parâmetro receberá o número de caracteres largos necessários para manter a URL criada.

Valor retornado

Retornará TRUE se a função for bem-sucedida ou FALSE caso contrário. Para obter dados de erro estendidos, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Código do Erro	Descrição
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
ERROR_NOT_ENOUGH_MEMORY	Memória insuficiente disponível para concluir a operação solicitada. (Código de erro do Windows)

Comentários

Mesmo quando WinHTTP é usado no modo assíncrono, ou seja, quando WINHTTP_FLAG_ASYNC foi definido em WinHttpOpen, essa função opera de forma síncrona. O valor retornado indica êxito ou falha. Para obter dados de erro estendidos, chame GetLastError.

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

 

Exemplos

O exemplo a seguir mostra como descompilar ou quebrar uma URL em seus subcomponentes, atualizar um componente e reconstruir a URL.

    URL_COMPONENTS urlComp;
    LPCWSTR pwszUrl1 = 
       L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
    DWORD dwUrlLen = 0;

    // Initialize the URL_COMPONENTS structure.
    ZeroMemory(&urlComp, sizeof(urlComp));
    urlComp.dwStructSize = sizeof(urlComp);

    // Set required component lengths to non-zero, 
    // so that they are cracked.
    urlComp.dwSchemeLength    = (DWORD)-1;
    urlComp.dwHostNameLength  = (DWORD)-1;
    urlComp.dwUrlPathLength   = (DWORD)-1;
    urlComp.dwExtraInfoLength = (DWORD)-1;

    // Crack the URL.
    if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
    {
        printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
    }
    else
    {
        // Change the search data. New data is the same length.
        urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";

        // Obtain the size of the new URL and allocate memory.
        WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
        LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];

        // Create a new URL.
        if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
        {
            printf( "Error %u in WinHttpCreateUrl.\n", GetLastError());
        }
        else
        {
            // Show both URLs.
            printf( "Old URL:  %S\nNew URL:  %S\n", pwszUrl1, pwszUrl2);
        }

        // Free allocated memory.
        delete [] pwszUrl2;
    }

Requisitos

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.

Confira também

Sobre os Serviços HTTP do Microsoft Windows (WinHTTP)

Manipulando localizadores de recursos uniformes

Versões do WinHTTP

WinHttpCrackUrl