WinHttpCreateUrl 函式 (winHTTP.h)

發行項
03/15/2023

WinHttpCreateUrl函式會從主機名稱和路徑等元件元件建立 URL。

語法

WINHTTPAPI BOOL WinHttpCreateUrl(
  [in]      LPURL_COMPONENTS lpUrlComponents,
  [in]      DWORD            dwFlags,
  [out]     LPWSTR           pwszUrl,
  [in, out] LPDWORD          pdwUrlLength
);

參數

[in] lpUrlComponents

包含要建立 URL 之元件之URL_COMPONENTS 結構的指標。

[in] dwFlags

控制此函式作業的旗標。此參數可以是下列其中一個值。

值	意義
ICU_ESCAPE	將所有不安全的字元轉換為lpszUrlPath成員所指向之路徑字串中對應的逸出序列，並在lpszExtraInfo中，將lpUrlComponents參數所指向之URL_COMPONENTS結構的成員所指向的額外資訊字串轉換成其對應的逸出序列。
ICU_REJECT_USERPWD	拒絕 URL 作為輸入，其中包含使用者名稱或密碼，或兩者。如果函式因為 URL 無效而失敗，後續對 GetLastError 的呼叫將會傳回ERROR_WINHTTP_INVALID_URL。

[out] pwszUrl

字元緩衝區的指標，該緩衝區會以寬字元的形式接收 URL， (Unicode) 字串。

[in, out] pdwUrlLength

不帶正負號長整數類型的變數指標，該變數會以寬 (Unicode) 字元接收 pwszUrl 緩衝區的長度。當函式傳回時，此參數會接收字元寬的 URL 字串長度，結尾字元為減 1。如果 GetLastError 傳回ERROR_INSUFFICIENT_BUFFER，此參數會收到保存所建立 URL 所需的寬字元數。

傳回值

如果函式成功，則傳回 TRUE ，否則傳回 FALSE 。若要取得擴充的錯誤資料，請呼叫 GetLastError。傳回的錯誤碼如下。

錯誤碼	描述
ERROR_WINHTTP_INTERNAL_ERROR	發生內部錯誤。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)

備註

即使 WinHTTP 用於非同步模式，亦即在WinHttpOpen中設定WINHTTP_FLAG_ASYNC時，此函式仍會同步運作。傳回值表示成功或失敗。若要取得擴充的錯誤資料，請呼叫 GetLastError。

注意針對 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 data. New data 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
程式庫	WinHTTP.lib
Dll	Winhttp.dll
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。