Função WinHttpCrackUrl (winhttp.h)

Artigo
11/20/2024

A função WinHttpCrackUrl separa uma URL em suas partes componentes, como nome do host e caminho.

Sintaxe

WINHTTPAPI BOOL WinHttpCrackUrl(
  [in]      LPCWSTR          pwszUrl,
  [in]      DWORD            dwUrlLength,
  [in]      DWORD            dwFlags,
  [in, out] LPURL_COMPONENTS lpUrlComponents
);

Parâmetros

[in] pwszUrl

Ponteiro para uma cadeia de caracteres que contém a URL canônica a ser separada. WinHttpCrackUrl não verifica se essa URL tem validade ou formato correto antes de tentar quebrá-la.

[in] dwUrlLength

O comprimento da cadeia de caracteres pwszUrl, em caracteres. Se dwUrlLength estiver definido como zero, WinHttpCrackUrl pressupõe que a cadeia de caracteres pwszUrl é nula terminada e determina o comprimento da cadeia de caracteres pwszUrl com base nessa suposição.

[in] dwFlags

Os sinalizadores que controlam a operação. Esse parâmetro pode ser uma combinação de um ou mais dos sinalizadores a seguir (os valores podem ser or'd bit a bit juntos). Ou o parâmetro pode ser 0, que não executa operações especiais.

Valor	Significado
ICU_DECODE	Converte caracteres que são "codificados para escape" (%xx) em seu formulário não escapado. Isso não decodifica outras codificações, como UTF-8. Esse recurso só poderá ser usado se o usuário fornecer buffers na estrutura URL_COMPONENTS para a qual copiar os componentes.
ICU_ESCAPE	Escapa determinados caracteres para suas sequências de escape (%xx). Os caracteres a serem escapados são caracteres não ASCII ou os caracteres ASCII que devem ser escapados para serem representados em uma solicitação HTTP. Esse recurso só poderá ser usado se o usuário fornecer buffers na estrutura URL_COMPONENTS para a qual copiar os componentes.
ICU_REJECT_USERPWD	Rejeita URLs como entrada que contêm credenciais inseridas (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.

[in, out] lpUrlComponents

Ponteiro para uma estrutura de URL_COMPONENTS que recebe os componentes de URL.

Valor de retorno

Retorna VERDADEIRO se a função for bem-sucedida ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Códigos de erro	Descrição
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
ERROR_WINHTTP_INVALID_URL	A URL é inválida.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	O esquema de URL não pôde ser reconhecido ou não tem suporte.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows)

Observações

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 informações de erro estendidas, chame GetLastError.

Os componentes necessários são indicados por membros da estrutura URL_COMPONENTS. Cada componente tem um ponteiro para o valor e tem um membro que armazena o comprimento do valor armazenado. Se o valor e o comprimento de um componente forem iguais a zero, esse componente não será retornado. Se o ponteiro para o valor do componente for NULL e o valor de seu membro de comprimento correspondente não for zero, o endereço do primeiro caractere do componente correspondente no pwszUrl cadeia de caracteres será armazenado no ponteiro e o comprimento do componente será armazenado no membro de comprimento.

Se o ponteiro contiver o endereço do buffer fornecido pelo usuário, o membro de comprimento deverá conter o tamanho do buffer. A função WinHttpCrackUrl copia o componente para o buffer e o membro de comprimento é definido como o comprimento do componente copiado, menos 1 para o terminador de cadeia de caracteres à direita. Se um buffer fornecido pelo usuário não for grande o suficiente, WinHttpCrackUrl retornará FALSE e GetLastError retornará ERROR_INSUFFICIENT_BUFFER.

Para que WinHttpCrackUrl funcionem corretamente, o tamanho da estrutura de URL_COMPONENTS deve ser armazenado no membro dwStructSize dessa estrutura.

Se o protocolo de Internet da URL passado para pwszUrl não for HTTP ou HTTPS, WinHttpCrackUrl retornará FALSE e GetLastError indicará
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

WinHttpCrackUrl não verifica a validade ou o formato de uma URL antes de tentar quebrá-la. Como resultado, se uma cadeia de caracteres como ""http://server?Bad=URL"" for passada, a função retornará resultados incorretos.

Observação para Windows XP e Windows 2000, consulte a seção requisitos de Run-Time da página inicial do WinHttp.

Exemplos

Este exemplo mostra como dividir uma URL em seus componentes, 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 information.  
        // New info 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

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

Consulte também

sobre o WinHTTP (Microsoft Windows HTTP Services)

tratando de recursos uniformes

versões do WinHTTP

WinHttpCreateUrl

Compartilhar via