URL (Uniform Resource Locator) 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 da 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 Servizi HTTP (WinHTTP) di Microsoft Windows offrono la possibilità di creare, combinare, suddividere e canonizzare gli URL. Per altre informazioni, vedere RFC 1738, Uniform Resource Locators e RFC 2396, URI (Uniform Resource Identifiers): Sintassi generica.

Che cos'è un URL canonico?

La sintassi e la semantica degli URL specificati lasciano spazio alla variazione e all'errore. La canonizzazione è il processo di normalizzazione di un URL effettivo in un formato corretto, standard, "canonico".

Ciò comporta la codifica di alcuni caratteri come "sequenze di escape". I caratteri alfanumerici US-ASCII 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 preceduta da caratteri di escape, inclusi i caratteri di controllo, lo spazio, il segno di percentuale, i "caratteri non sicuri" ( <, >, , #, {, }, |, \, ^, ~, [, ]e ' ) e tutti i caratteri con un punto di codice superiore a 127.

Uso delle funzioni WinHTTP per gestire gli URL

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

Separazione degli URL

La funzionewinHttpCrackUrlsepara 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 informazioni aggiuntive, ad esempio i parametri di ricerca. Ogni componente, ad eccezione dello schema e dei 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 determinato componente nella struttura URL_COMPONENTS, il membro che archivia la lunghezza della stringa di tale componente deve essere impostato 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 funzionewinHttpCrackUrlrestituisce le informazioni sul componente come stringa nel buffer e archivia la lunghezza della stringa nel membro di 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 che contiene le informazioni sul componente e imposta la lunghezza della stringa sul numero di caratteri nella parte rimanente della stringa URL relativa al componente.

Tutti i membri del puntatore impostati su NULL con un punto membro di lunghezza diversa da zero al punto iniziale appropriato nella stringa URL. La lunghezza archiviata nel membro length deve essere utilizzata per determinare la fine delle informazioni del singolo componente.

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

Creazione di URL

La funzioneWinHttpCreateUrl usa le informazioni contenute nella struttura URL_COMPONENTS descritta in precedenza per creare un URL.

Per ogni componente necessario, il membro del puntatore deve contenere un puntatore al buffer che contiene le informazioni. Il membro length deve essere impostato su zero se il membro del puntatore contiene un puntatore a una stringa con terminazione zero; Il membro length deve essere impostato sulla lunghezza della stringa se il membro del puntatore contiene un puntatore a una stringa che non termina con 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 il WinHttpCrackUrl e WinHttpCreateUrl per disassemblare un URL esistente, modificarne uno 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;
  }