WinHttpCrackUrl-Funktion (winhttp.h)

Artikel
11/20/2024

Die WinHttpCrackUrl Funktion trennt eine URL in die Komponententeile 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

Zeigen Sie auf eine Zeichenfolge, die die kanonische URL enthält, die getrennt werden soll. WinHttpCrackUrl- überprüft diese URL nicht auf Gültigkeit oder korrektes Format, bevor Sie versuchen, es zu knacken.

[in] dwUrlLength

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

[in] dwFlags

Die Flags, die den Vorgang steuern. Dieser Parameter kann eine Kombination aus einer oder mehreren der folgenden Flags sein (Werte können bitweise OR'd zusammen sein). Oder der Parameter kann 0 sein, wodurch keine speziellen Vorgänge ausgeführt werden.

Wert	Bedeutung
ICU_DECODE	Konvertiert Zeichen, die "escapecodiert" (%xx) sind, in ihr Nicht-Escape-Formular. 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 sollen.
ICU_ESCAPE	Escapet bestimmte Zeichen zu ihren Escapesequenzen (%xx). Zeichen, die escaped sein sollen, sind Nicht-ASCII-Zeichen oder ASCII-Zeichen, die in einer HTTP-Anforderung als Escapezeichen dargestellt werden müssen. Dieses Feature kann nur verwendet werden, wenn der Benutzer Puffer in der URL_COMPONENTS Struktur bereitstellt, in die die Komponenten kopiert werden sollen.
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_URLzurück.

[in, out] lpUrlComponents

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

Rückgabewert

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

Fehlercodes	Beschreibung
ERROR_WINHTTP_INTERNAL_ERROR	Interner Fehler.
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	Nicht genügend Arbeitsspeicher war verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

Bemerkungen

Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpenfestgelegt wurde), wird diese Funktion synchron ausgeführt. Der Rückgabewert gibt Erfolg oder Fehler an. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Die erforderlichen Komponenten werden durch Elemente der URL_COMPONENTS Struktur angegeben. Jede Komponente weist einen Zeiger auf den Wert auf und verfügt über ein Element, das die Länge des gespeicherten Werts speichert. Wenn sowohl der Wert als auch die Länge einer Komponente gleich Null sind, wird diese Komponente nicht zurückgegeben. Wenn der Zeiger auf den Wert der Komponente NULL- ist und der Wert des entsprechenden Längenelements ungleich Null 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 das Längenelement die Größe des Puffers enthalten. Die WinHttpCrackUrl--Funktion kopiert die Komponente in den Puffer, und das Längenelement wird auf die Länge der kopierten Komponente festgelegt, minus 1 für den nachfolgenden Zeichenfolgenendpunkt. Wenn ein vom Benutzer bereitgestellter Puffer nicht groß genug ist, gibt WinHttpCrackUrlFALSE-zurück, und GetLastError- gibt ERROR_INSUFFICIENT_BUFFERzurück.

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

Wenn das Internetprotokoll der für pwszUr l übergebenen URL nicht HTTP oder HTTPS ist, gibt WinHttpCrackUrlFALSE- zurück und GetLastError- an.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

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

Hinweis für Windows XP und Windows 2000 finden Sie im Abschnitt Run-Time Anforderungen 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

Anforderung	Wert
mindestens unterstützte Client-	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winhttp.h
Library	Winhttp.lib
DLL-	Winhttp.dll
redistributable	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.

Siehe auch

Über Microsoft Windows HTTP Services (WinHTTP)

Behandeln von Uniform Resource Locators

WinHTTP-Versionen

WinHttpCreateUrl-

Freigeben über