URL (Uniform Resource Locators) in WinHTTP

Un URL è una rappresentazione compatta della posizione e del metodo di accesso per una risorsa che si trova su Internet. Ogni URL è costituito da uno schema (HTTP, HTTPS, FTP o Gopher) e una stringa specifica dello schema. Questa stringa può includere anche una combinazione di un percorso di directory, una stringa di ricerca o un nome della risorsa. Le funzioni di Microsoft Windows HTTP Services (WinHTTP) offrono la possibilità di creare, combinare, suddividere e canonizzare gli URL. Per altre informazioni, vedere RFC 1738, Localizzatori di risorse uniformi e RFC 2396, URI (Uniform Resource Identifiers): sintassi generica.

Che cos'è un URL canonico?

La sintassi e la semantica specificati degli URL lascia spazio per la variazione e l'errore. La canonizzazione è il processo di normalizzazione di un URL effettivo in una forma corretta, standard, "canonica".

Ciò implica la codifica di alcuni caratteri come "sequenze di escape". I caratteri US-ASCII alfanumerici non devono essere codificati (le cifre 0-9, le lettere maiuscole A-Z e le lettere minuscole a-z). La maggior parte degli altri caratteri deve essere escape, inclusi i caratteri di controllo, il carattere di spazio, il segno percentuale , "caratteri non sicuri" ( <, >, # , {, }, |, ^, ^, ~, [, ]e ' e tutti i caratteri con un punto di codice superiore al 127.

Uso delle funzioni WinHTTP per gestire gli URL

WinHTTP offre due funzioni per la gestione degli URL. WinHttpCrackUrl separa un URL nelle parti dei componenti e WinHttpCreateUrl crea un URL dai componenti.

Separazione degli URL

La funzione WinHttpCrackUrl separa un URL nelle parti del componente e restituisce i componenti indicati dalla struttura URL_COMPONENTS passata alla funzione.

I componenti che costituiscono la struttura URL_COMPONENTS sono il numero di schema, il nome host, il numero di porta, il nome utente, la password, il percorso URL e altre informazioni, ad esempio i parametri di ricerca. Ogni componente, tranne lo schema e i numeri di porta, ha un membro stringa che contiene le informazioni e un membro che contiene la lunghezza del membro stringa. Lo schema e i numeri di porta hanno solo un membro che archivia il valore corrispondente; sia lo schema che i numeri di porta vengono restituiti in tutte le chiamate riuscite a WinHttpCrackUrl.

Per recuperare il valore di un componente specifico nella struttura URL_COMPONENTS , il membro che archivia la lunghezza della stringa di tale componente deve essere impostata su un valore diverso da zero. Il membro stringa può essere un puntatore a un buffer o NULL.

Se il membro del puntatore contiene un puntatore a un buffer, il membro della lunghezza della stringa deve contenere le dimensioni del buffer. La funzione WinHttpCrackUrl restituisce le informazioni del componente come stringa nel buffer e archivia la lunghezza della stringa nel membro della lunghezza della stringa.

Se il membro del puntatore è impostato su NULL, il membro della lunghezza della stringa può essere impostato su qualsiasi valore diverso da zero. La funzione WinHttpCrackUrl archivia un puntatore al primo carattere della stringa URL contenente le informazioni del componente e imposta la lunghezza della stringa sul numero di caratteri nella parte rimanente della stringa URL che riguarda il componente.

Tutti i membri del puntatore impostati su NULL con un membro di lunghezza non zero puntano al punto di partenza appropriato nella stringa URL. La lunghezza archiviata nel membro di lunghezza deve essere usata per determinare la fine delle informazioni del singolo componente.

Per completare l'inizializzazione della struttura URL_COMPONENTS correttamente, il membro dwStructSize deve essere impostato sulle dimensioni della struttura URL_COMPONENTS .

Creazione di URL

La funzione WinHttpCreateUrl usa le informazioni nella struttura descritta in precedenza URL_COMPONENTS per creare un URL.

Per ogni componente richiesto, il membro puntatore deve contenere un puntatore al buffer che contiene le informazioni. Il membro di lunghezza deve essere impostato su zero se il membro puntatore contiene un puntatore a una stringa con terminazione zero; il membro di lunghezza deve essere impostato sulla lunghezza della stringa se il membro puntatore contiene un puntatore a una stringa non terminata zero. Il membro puntatore di tutti i componenti non necessari deve essere impostato su NULL.

Codice di esempio

Il codice di esempio seguente illustra come usare WinHttpCrackUrl e WinHttpCreateUrl per disassemblare un URL esistente, modificare uno dei relativi componenti e riassemblarlo in un nuovo 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;
  }