Ujednolicone lokalizatory zasobów (adresy URL) w usłudze WinHTTP

Adres URL to kompaktowa reprezentacja lokalizacji i metody dostępu dla zasobu znajdującego się w Internecie. Każdy adres URL składa się ze schematu (HTTP, HTTPS, FTP lub Gopher) i ciągu specyficznego dla schematu. Ten ciąg może również zawierać kombinację ścieżki katalogu, ciągu wyszukiwania lub nazwy zasobu. Funkcje usług HTTP systemu Microsoft Windows (WinHTTP) umożliwiają tworzenie, łączenie, podział i kanoniczne adresy URL. Aby uzyskać więcej informacji, zobacz RFC 1738, uniform resource locators i RFC 2396, Uniform Resource Identifiers (URI): Składnia ogólna.

Co to jest kanoniczny adres URL?

Określona składnia i semantyka adresów URL pozostawia miejsce na odmiany i błędy. Canonicalization to proces normalizacji rzeczywistego adresu URL w poprawny, standardowy, "kanoniczny".

Obejmuje to kodowanie niektórych znaków jako "sekwencji ucieczki". Znaki alfanumeryczne US-ASCII nie muszą być kodowane (cyfry 0–9, wielkie litery A–Z i małe litery a-z). Większość innych znaków musi zostać unikniętą, w tym znaków kontrolnych, znaku spacji, znaku procentowego, "niebezpiecznych znaków" ( <, >, ", ", #, {, {, }, |, \, ^, ~, [, ], i ' ) oraz wszystkich znaków z punktem kodu powyżej 127.

Obsługa adresów URL przy użyciu funkcji WinHTTP

WinHTTP udostępnia dwie funkcje do obsługi adresów URL. WinHttpCrackUrl oddziela adres URL na jego części składników, a WinHttpCreateUrl tworzy adres URL ze składników.

Oddzielanie adresów URL

Funkcja WinHttpCrackUrl oddziela adres URL w jego części składników i zwraca składniki wskazane przez strukturę URL_COMPONENTS przekazywaną do funkcji.

Składniki tworzące strukturę URL_COMPONENTS to numer schematu, nazwa hosta, numer portu, nazwa użytkownika, hasło, ścieżka adresu URL i dodatkowe informacje, takie jak parametry wyszukiwania. Każdy składnik, z wyjątkiem schematu i numerów portów, ma składową ciągu, która zawiera informacje i element członkowski, który przechowuje długość składowej ciągu. Schemat i numery portów mają tylko element członkowski, który przechowuje odpowiednią wartość; zarówno schemat, jak i numery portów są zwracane we wszystkich pomyślnych wywołaniach WinHttpCrackUrl.

Aby pobrać wartość określonego składnika w strukturze URL_COMPONENTS, element członkowski przechowujący długość ciągu tego składnika musi być ustawiony na wartość niezerową. Element członkowski ciągu może być wskaźnikiem do buforu lub null.

Jeśli element członkowski wskaźnika zawiera wskaźnik do buforu, element członkowski długości ciągu musi zawierać rozmiar tego buforu. Funkcja WinHttpCrackUrl zwraca informacje o składniku jako ciąg w buforze i przechowuje długość ciągu w składowej długości ciągu.

Jeśli element członkowski wskaźnika ma wartość null, można ustawić element członkowski długości ciągu na dowolną wartość niezerową. Funkcja WinHttpCrackUrl przechowuje wskaźnik do pierwszego znaku ciągu adresu URL zawierającego informacje o składniku i ustawia długość ciągu na liczbę znaków w pozostałej części ciągu adresu URL odnoszącego się do składnika.

Wszystkie elementy członkowskie wskaźnika ustawione na wartość null z punktem członkowskim o długości niezerowej do odpowiedniego punktu początkowego w ciągu adresu URL. Długość składowana w elemencie długości musi służyć do określenia końca informacji poszczególnych składników.

Aby zakończyć prawidłowe inicjowanie struktury URL_COMPONENTS, należy ustawić element członkowski dwStructSize na rozmiar struktury URL_COMPONENTS.

Tworzenie adresów URL

FunkcjaWinHttpCreateUrl używa informacji w wcześniej opisanej strukturze URL_COMPONENTS w celu utworzenia adresu URL.

Dla każdego wymaganego składnika element członkowski wskaźnika powinien zawierać wskaźnik do buforu zawierającego informacje. Element członkowski długości powinien być ustawiony na zero, jeśli element członkowski wskaźnika zawiera wskaźnik do ciągu bez zakończenia; element członkowski długości powinien być ustawiony na długość ciągu, jeśli element członkowski wskaźnika zawiera wskaźnik do ciągu, który nie jest zakończony zero. Element członkowski wskaźnika dla wszystkich składników, które nie są wymagane, musi być ustawiony na wartość null.

Przykładowy kod

Poniższy przykładowy kod pokazuje, jak używać WinHttpCrackUrl i WinHttpCreateUrl dezasemblować istniejący adres URL, zmodyfikować jeden z jego składników i ponownie utworzyć go w nowym adresie 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;
  }