通过

WinHttpCrackUrl 函数 （winhttp.h）

  • 项目

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

语法

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

参数

[in] pwszUrl

指向包含要分隔的规范 URL 的字符串的指针。 WinHttpCrackUrl 在尝试破解 URL 之前，不会检查此 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 字符串 中相应组件的第一个字符的地址存储在指针中，并且组件的长度存储在长度成员中。

如果指针包含用户提供的缓冲区的地址，长度成员必须包含缓冲区的大小。 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 起始页的 Run-Time 要求 部分。
 

例子

此示例演示如何将 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;
    }

要求

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

另请参阅

关于 Microsoft Windows HTTP 服务 （WinHTTP）

处理统一资源定位符

WinHTTP 版本

WinHttpCreateUrl