WinHttpCrackUrl-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpCrackUrl-Funktion unterteilt eine URL in ihre Komponenten wie Hostname und Pfad.

Syntax

WINHTTPAPI BOOL WinHttpCrackUrl(
  [in]      LPCWSTR          pwszUrl,
  [in]      DWORD            dwUrlLength,
  [in]      DWORD            dwFlags,
  [in, out] LPURL_COMPONENTS lpUrlComponents
);

Parameter

[in] pwszUrl

Zeiger auf eine Zeichenfolge, die die zu trennende kanonische URL enthält. WinHttpCrackUrl überprüft diese URL nicht auf Gültigkeit oder korrektes Format, bevor sie versucht, sie zu knacken.

[in] dwUrlLength

Die Länge der pwszUrl-Zeichenfolge in Zeichen. Wenn dwUrlLength auf 0 festgelegt ist, geht WinHttpCrackUrl davon aus, dass die pwszUrl-Zeichenfolgenull beendet ist, und bestimmt die Länge der pwszUrl-Zeichenfolge basierend auf dieser Annahme.

[in] dwFlags

Die Flags, die den Vorgang steuern. Dieser Parameter kann eine Kombination aus mindestens einem der folgenden Flags sein (Werte können bitweise ODER zusammen sein). Oder der Parameter kann 0 sein, wodurch keine besonderen Vorgänge ausgeführt werden.

Wert	Bedeutung
ICU_DECODE	Konvertiert Zeichen, die "escapecodiert" (%xx) sind, in ihre Nicht-Escape-Form. Dadurch werden keine anderen Codierungen wie UTF-8 decodiert. Dieses Feature kann nur verwendet werden, wenn der Benutzer Puffer in der URL_COMPONENTS Struktur bereitstellt, in die die Komponenten kopiert werden können.
ICU_ESCAPE	Escapen von bestimmten Zeichen in ihre Escapesequenzen (%xx). Zeichen, die mit Escapezeichen versehen werden sollen, sind Nicht-ASCII-Zeichen oder die ASCII-Zeichen, die mit Escapezeichen versehen werden müssen, um in einer HTTP-Anforderung dargestellt zu werden. Dieses Feature kann nur verwendet werden, wenn der Benutzer Puffer in der URL_COMPONENTS Struktur bereitstellt, in die die Komponenten kopiert werden können.
ICU_REJECT_USERPWD	Lehnt URLs als Eingabe ab, die eingebettete Anmeldeinformationen enthalten (entweder ein Benutzername, ein Kennwort oder beides). Wenn die Funktion aufgrund einer ungültigen URL fehlschlägt, geben nachfolgende Aufrufe von GetLastError ERROR_WINHTTP_INVALID_URL zurück.

[in, out] lpUrlComponents

Zeiger auf eine URL_COMPONENTS-Struktur , die die URL-Komponenten empfängt.

Rückgabewert

Gibt TRUE zurück, wenn die Funktion erfolgreich ist, oder andernfalls FALSE . Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercodes	BESCHREIBUNG
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_WINHTTP_INVALID_URL	Die URL ist ungültig.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Das URL-Schema konnte nicht erkannt werden oder wird nicht unterstützt.
ERROR_NOT_ENOUGH_MEMORY	Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Hinweise

Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), arbeitet diese Funktion synchron. Der Rückgabewert weist auf Erfolg oder Fehler hin. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Die erforderlichen Komponenten werden durch Elemente der URL_COMPONENTS-Struktur angegeben. Jede Komponente verfügt über einen Zeiger auf den Wert und einen Member, der die Länge des gespeicherten Werts speichert. Wenn sowohl der Wert als auch die Länge für eine Komponente gleich 0 sind, wird diese Komponente nicht zurückgegeben. Wenn der Zeiger auf den Wert der Komponente nicht NULL und der Wert des entsprechenden Längenelements nonzero ist, wird die Adresse des ersten Zeichens der entsprechenden Komponente in der pwszUrl-Zeichenfolge im Zeiger gespeichert, und die Länge der Komponente wird im Längenelement gespeichert.

Wenn der Zeiger die Adresse des vom Benutzer bereitgestellten Puffers enthält, muss der Längenelement die Größe des Puffers enthalten. Die WinHttpCrackUrl-Funktion kopiert die Komponente in den Puffer, und das Längenelement ist auf die Länge der kopierten Komponente festgelegt, minus 1 für den nachfolgenden Zeichenfolgenabschluss. Wenn ein vom Benutzer bereitgestellter Puffer nicht groß genug ist, gibt WinHttpCrackUrlFALSE zurück, und GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück.

Damit WinHttpCrackUrl ordnungsgemäß funktioniert, muss die Größe der URL_COMPONENTS-Struktur im dwStructSize-Member dieser Struktur gespeichert werden.

Wenn das Internetprotokoll der für pwszUrl übergebenen URL nicht HTTP oder HTTPS ist, gibt WinHttpCrackUrlFALSE und GetLastError an.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

WinHttpCrackUrl überprüft nicht die Gültigkeit oder das Format einer URL, bevor sie versucht, sie zu knacken. Wenn daher eine Zeichenfolge wie ""http://server?Bad=URL"" übergeben wird, gibt die Funktion falsche Ergebnisse zurück.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHttp-Startseite .

Beispiele

In diesem Beispiel wird gezeigt, wie sie eine URL in ihre Komponenten aufteilen, eine Komponente aktualisieren und dann die URL rekonstruieren.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll
Verteilbare Komponente	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.