WinHttpCrackUrl 函数 (winhttp.h)

项目
08/27/2023

WinHttpCrackUrl 函数将 URL 分隔为其组件部分，例如主机名和路径。

语法

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

参数

[in] pwszUrl

指向包含要分隔的规范 URL 的字符串的指针。 WinHttpCrackUrl 在尝试破解之前，不会检查此 URL 的有效性或正确的格式。

[in] dwUrlLength

pwszUrl 字符串的长度（以字符为单位）。如果将 dwUrlLength 设置为零， 则 WinHttpCrackUrl 假定 pwszUrl 字符串以 null 结尾，并根据该假设确定 pwszUrl 字符串的长度。

[in] dwFlags

控制操作的标志。此参数可以是以下一个或多个标志的组合， (值可以是按位 OR) 。或者，参数可以为 0，这不执行任何特殊操作。

值	含义
ICU_DECODE	将“转义编码” (%xx) 字符转换为非转义形式。这不会解码其他编码，例如 UTF-8。仅当用户在 URL_COMPONENTS 结构中提供要将组件复制到的缓冲区时，才能使用此功能。
ICU_ESCAPE	将某些字符转义为转义序列 (%xx) 。要转义的字符是非 ASCII 字符或必须转义才能在 HTTP 请求中表示的 ASCII 字符。仅当用户在 URL_COMPONENTS 结构中提供要将组件复制到的缓冲区时，才能使用此功能。
ICU_REJECT_USERPWD	拒绝 URL 作为包含嵌入凭据的输入， (用户名、密码或两者) 。如果函数因 URL 无效而失败，则对 GetLastError 的后续调用将返回 ERROR_WINHTTP_INVALID_URL。

[in, out] lpUrlComponents

指向接收 URL 组件的 URL_COMPONENTS 结构的指针。

返回值

如果函数成功，则返回 TRUE ;否则返回 FALSE 。要获得更多的错误信息，请调用 GetLastError。返回的错误代码如下。

错误代码	说明
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_WINHTTP_INVALID_URL	URL 无效。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	无法识别或不支持 URL 方案。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。返回值指示成功或失败。要获得更多的错误信息，请调用 GetLastError。

所需的组件由 URL_COMPONENTS 结构的成员指示。每个组件都有一个指向值的指针，并且有一个用于存储存储值的长度的成员。如果组件的值和长度都等于零，则不返回该组件。如果指向组件值的指针不是 NULL ，并且其相应长度成员的值为非零值，则 pwszUrl 字符串中相应组件的第一个字符的地址存储在指针中，并且组件的长度存储在 length 成员中。

如果指针包含用户提供的缓冲区的地址，则 length 成员必须包含缓冲区的大小。 WinHttpCrackUrl 函数将组件复制到缓冲区中，长度成员设置为复制的组件的长度，尾随字符串终止符为减 1。如果用户提供的缓冲区不够大， WinHttpCrackUrl 返回 FALSE， GetLastError 返回 ERROR_INSUFFICIENT_BUFFER。

要使 WinHttpCrackUrl 正常工作， URL_COMPONENTS 结构的大小必须存储在该结构的 dwStructSize 成员中。

如果为 pwszUrl 传递的 URL 的 Internet 协议不是 HTTP 或 HTTPS，则 WinHttpCrackUrl 返回 FALSE ， GetLastError 指示
ERROR_WINHTTP_UNRECOGNIZED_SCHEME。

WinHttpCrackUrl 在尝试破解 URL 之前不会检查 URL 的有效性或格式。因此，如果传入“”http://server?Bad=URL"“等字符串，函数将返回不正确的结果。

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

示例

此示例演示如何将 URL 拆分为其组件、更新组件，然后重新构造 URL。

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

要求


最低受支持的客户端	Windows XP、Windows 2000 Professional 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。