URLs (Uniform Resource Locators) no WinHTTP

Artigo
06/13/2023

Uma URL é uma representação compacta do método de localização e acesso para um recurso localizado na Internet. Cada URL consiste em um esquema (HTTP, HTTPS, FTP ou Gopher) e uma cadeia de caracteres específica do esquema. Essa cadeia de caracteres também pode incluir uma combinação de um caminho de diretório, uma cadeia de caracteres de pesquisa ou um nome do recurso. As funções WinHTTP (Microsoft Windows HTTP Services) fornecem a capacidade de criar, combinar, dividir e canonizar URLs. Para obter mais informações, consulte RFC 1738, Uniform Resource Locators e RFC 2396, Uniform Resource Identifiers (URI): Sintaxe genérica.

O que é uma URL canônica?

A sintaxe e a semântica especificadas das URLs deixam espaço para variação e erro. A canonicalização é o processo de normalizar uma URL real em uma forma correta, padrão e "canônica".

Isso envolve codificar alguns caracteres como "sequências de escape". Caracteres ALFAnuméricos US-ASCII não precisam ser codificados (os dígitos 0-9, as letras maiúsculas A-Z e as letras minúsculas a-z). A maioria dos outros caracteres deve ser escapada, incluindo caracteres de controle, o caractere de espaço, o sinal de porcentagem, "caracteres não seguros" ( <, >, ", ", #, {, }, |, \, ^, ~, [, ], e ' ) e todos os caracteres com um ponto de código acima de 127.

Usando as funções WinHTTP para manipular URLs

O WinHTTP fornece duas funções para lidar com URLs. WinHttpCrackUrl separa uma URL em suas partes de componente e WinHttpCreateUrl cria uma URL de componentes.

Separando URLs

A função WinHttpCrackUrl separa uma URL em suas partes de componente e retorna os componentes indicados pela estrutura URL_COMPONENTS que é passada para a função.

Os componentes que compõem a estrutura URL_COMPONENTS são o número do esquema, o nome do host, o número da porta, o nome de usuário, a senha, o caminho da URL e informações adicionais, como parâmetros de pesquisa. Cada componente, exceto os números de esquema e porta, tem um membro de cadeia de caracteres que contém as informações e um membro que contém o comprimento do membro da cadeia de caracteres. O esquema e os números de porta têm apenas um membro que armazena o valor correspondente; os números do esquema e da porta são retornados em todas as chamadas bem-sucedidas para WinHttpCrackUrl.

Para recuperar o valor de um componente específico na estrutura URL_COMPONENTS , o membro que armazena o comprimento da cadeia de caracteres desse componente deve ser definido como um valor diferente de zero. O membro da cadeia de caracteres pode ser um ponteiro para um buffer ou NULL.

Se o membro do ponteiro contiver um ponteiro para um buffer, o membro de comprimento da cadeia de caracteres deverá conter o tamanho desse buffer. A função WinHttpCrackUrl retorna as informações do componente como uma cadeia de caracteres no buffer e armazena o comprimento da cadeia de caracteres no membro de comprimento da cadeia de caracteres.

Se o membro do ponteiro for definido como NULL, o membro de comprimento da cadeia de caracteres poderá ser definido como qualquer valor diferente de zero. A função WinHttpCrackUrl armazena um ponteiro para o primeiro caractere da cadeia de caracteres de URL que contém as informações do componente e define o comprimento da cadeia de caracteres como o número de caracteres na parte restante da cadeia de caracteres de URL que pertence ao componente.

Todos os membros de ponteiro definidos como NULL com um ponto de membro de comprimento diferente de zero para o ponto de partida apropriado na cadeia de caracteres de URL. O comprimento armazenado no membro de comprimento deve ser usado para determinar o final das informações do componente individual.

Para concluir a inicialização correta da estrutura URL_COMPONENTS , o membro dwStructSize deve ser definido como o tamanho da estrutura URL_COMPONENTS .

Criando URLs

A função WinHttpCreateUrl usa as informações na estrutura de URL_COMPONENTS descrita anteriormente para criar uma URL.

Para cada componente necessário, o membro do ponteiro deve conter um ponteiro para o buffer que contém as informações. O membro de comprimento deverá ser definido como zero se o membro do ponteiro contiver um ponteiro para uma cadeia de caracteres terminada em zero; o membro de comprimento deverá ser definido como o comprimento da cadeia de caracteres se o membro do ponteiro contiver um ponteiro para uma cadeia de caracteres que não seja terminada em zero. O membro ponteiro de todos os componentes que não são necessários deve ser definido como NULL.

Código de exemplo

O código de exemplo a seguir mostra como usar WinHttpCrackUrl e WinHttpCreateUrl para desmontar uma URL existente, modificar um de seus componentes e reagrupá-la em uma nova URL.

  URL_COMPONENTS urlComp;
  LPCWSTR pwszUrl1 = 
    L"https://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;
  }

Compartilhar via