Uniform Resource Locators (URLs) in WinHTTP

Eine URL ist eine kompakte Darstellung des Standorts und der Zugriffsmethode für eine Ressource im Internet. Jede URL besteht aus einem Schema (HTTP, HTTPS, FTP oder Gopher) und einer schemaspezifischen Zeichenfolge. Diese Zeichenfolge kann auch eine Kombination aus einem Verzeichnispfad, einer Suchzeichenfolge oder einem Namen der Ressource enthalten. Die Microsoft Windows HTTP Services (WinHTTP)-Funktionen bieten die Möglichkeit, URLs zu erstellen, zu kombinieren, aufzuschlüsseln und zu kanonisieren. Weitere Informationen finden Sie unter RFC 1738, Uniform Resource Locators und RFC 2396, Uniform Resource Identifiers (URI): Generische Syntax.

Was ist eine kanonische URL?

Die angegebene Syntax und Semantik von URLs lassen Platz für Variation und Fehler. Die Kanonisierung ist der Prozess der Normalisierung einer tatsächlichen URL in einer korrekten, standardmäßigen ,kanonischen" Form.

Dies umfasst das Codieren einiger Zeichen als "Escapesequenzen". Alphanumerische US-ASCII Zeichen müssen nicht codiert werden (die Ziffern 0-9, die Großbuchstaben A-Z und die Kleinbuchstaben a-z). Die meisten anderen Zeichen müssen escapezeichen sein, einschließlich Steuerzeichen, Leerzeichen, Prozentzeichen, "unsichere Zeichen" ( <, >, ", #, {, }, |, \, ^, ~, [, ], und ' ) und alle Zeichen mit einem Codepunkt oberhalb von 127.

Verwenden der WinHTTP-Funktionen zum Behandeln von URLs

WinHTTP stellt zwei Funktionen zum Behandeln von URLs bereit. WinHttpCrackUrl trennt eine URL in die Komponententeile, und WinHttpCreateUrl erstellt eine URL aus Komponenten.

Trennen von URLs

Die WinHttpCrackUrl--Funktion trennt eine URL in die Komponententeile und gibt die komponenten zurück, die durch die URL_COMPONENTS Struktur angegeben sind, die an die Funktion übergeben wird.

Die Komponenten, aus denen die URL_COMPONENTS Struktur besteht, sind die Schemanummer, der Hostname, die Portnummer, der Benutzername, das Kennwort, der URL-Pfad und zusätzliche Informationen wie Suchparameter. Jede Komponente mit Ausnahme der Schema- und Portnummern verfügt über ein Zeichenfolgenelement, das die Informationen und ein Element enthält, das die Länge des Zeichenfolgenelements enthält. Die Schema- und Portnummern weisen nur ein Element auf, das den entsprechenden Wert speichert; Sowohl die Schema- als auch die Portnummern werden für alle erfolgreichen Aufrufe an WinHttpCrackUrlzurückgegeben.

Um den Wert einer bestimmten Komponente in der URL_COMPONENTS-Struktur abzurufen, muss das Element, das die Zeichenfolgenlänge dieser Komponente speichert, auf einen Wert ungleich Null festgelegt werden. Das Zeichenfolgenelement kann entweder ein Zeiger auf einen Puffer oder NULL-sein.

Wenn das Zeigerelement einen Zeiger auf einen Puffer enthält, muss das Zeichenfolgenlängenelement die Größe dieses Puffers enthalten. Die WinHttpCrackUrl Funktion gibt die Komponenteninformationen als Zeichenfolge im Puffer zurück und speichert die Zeichenfolgenlänge im Zeichenfolgenlängenelement.

Wenn das Zeigerelement auf NULL-festgelegt ist, kann das Zeichenfolgenlängenelement auf einen beliebigen Wert ungleich Null festgelegt werden. Die WinHttpCrackUrl--Funktion speichert einen Zeiger auf das erste Zeichen der URL-Zeichenfolge, die die Komponenteninformationen enthält, und legt die Zeichenfolgenlänge auf die Anzahl der Zeichen im verbleibenden Teil der URL-Zeichenfolge fest, die sich auf die Komponente bezieht.

Alle Zeigermember werden auf NULL- festgelegt, wobei ein Memberpunkt ungleich Null auf den entsprechenden Startpunkt in der URL-Zeichenfolge festgelegt ist. Die im Längenelement gespeicherte Länge muss verwendet werden, um das Ende der Informationen der einzelnen Komponenten zu bestimmen.

Um die Initialisierung der URL_COMPONENTS Struktur ordnungsgemäß abzuschließen, muss die dwStructSize Member auf die Größe der URL_COMPONENTS Struktur festgelegt werden.

Erstellen von URLs

Die WinHttpCreateUrl--Funktion verwendet die Informationen in der zuvor beschriebenen URL_COMPONENTS Struktur, um eine URL zu erstellen.

Für jede erforderliche Komponente sollte das Zeigerelement einen Zeiger auf den Puffer enthalten, der die Informationen enthält. Das Längenelement sollte auf Null festgelegt werden, wenn das Zeigerelement einen Zeiger auf eine leere Zeichenfolge enthält. Das Längenelement sollte auf die Zeichenfolgenlänge festgelegt werden, wenn das Zeigerelement einen Zeiger auf eine Zeichenfolge enthält, die nicht null beendet ist. Das Zeigerelement aller Komponenten, die nicht erforderlich sind, muss auf NULL-festgelegt werden.

Beispielcode

Im folgenden Beispielcode wird gezeigt, wie Sie die WinHttpCrackUrl- und WinHttpCreateUrl- verwenden, um eine vorhandene URL zu zerlegen, eine der zugehörigen Komponenten zu ändern und erneut in einer neuen URL zusammenzufügen.

  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;
  }