WinHTTP 中的統一資源定位器 (URL)

發行項
06/13/2023

URL 是位於網際網路之資源的位置和存取方法的精簡標記法。每個 URL 都包含 (HTTP、HTTPS、FTP 或 Gopher) 和配置特定字串的配置。此字串也可以包含目錄路徑、搜尋字串或資源名稱的組合。 Microsoft Windows HTTP Services (WinHTTP) 函式可讓您建立、合併、細分及正式化 URL。如需詳細資訊，請參閱 RFC 1738、統一資源定位器和 RFC 2396、統一資源識別項 (URI) ：一般語法。

什麼是標準 URL？

指定的 URL 語法和語意會留下變化和錯誤的空間。標準化是將實際 URL 正規化為正確、標準、「標準」格式的程式。

這牽涉到將某些字元編碼為「逸出序列」。英數位元 US-ASCII 字元不需要編碼 (數位 0-9、大寫字母 A-Z 和小寫字母 a-z) 。大部分的其他字元都必須逸出，包括控制字元、空白字元、百分比符號、「unsafe characters」 ( < 、 > 、、「、#、{、}、|、\、^、~、[、]、' ) ，以及具有 127 以上代碼點的所有字元。

使用 WinHTTP 函式來處理 URL

WinHTTP 提供兩個函式來處理 URL。 WinHttpC，Url 會將 URL 分成其元件元件，而 WinHttpCreateUrl 會從元件建立 URL。

分隔 URL

WinHttpC，Url函式會將 URL 分成其元件元件，並傳回傳遞至函式之 URL_COMPONENTS結構所指示的元件。

構成 URL_COMPONENTS 結構的元件是配置編號、主機名稱、埠號碼、使用者名稱、密碼、URL 路徑，以及其他資訊，例如搜尋參數。除了配置和埠號碼以外，每個元件都有保存資訊的字串成員，以及保存字串成員長度的成員。配置和埠號碼只有儲存對應值的成員;配置和埠號碼都會在所有成功呼叫 WinHttpC一Url時傳回。

若要擷取 URL_COMPONENTS 結構中特定元件的值，儲存該元件之字串長度的成員必須設定為非零值。字串成員可以是緩衝區或 Null的指標。

如果指標成員包含緩衝區的指標，字串長度成員必須包含該緩衝區的大小。 WinHttpC，Url函式會以緩衝區中的字串的形式傳回元件資訊，並將字串長度儲存在字串長度成員中。

如果指標成員設定為 Null，字串長度成員可以設定為任何非零值。 WinHttpC，Url函式會儲存 URL 字串的第一個字元指標，其中包含元件資訊，並將字串長度設定為與元件相關之 URL 字串其餘部分中的字元數。

所有指標成員都設定為 Null ，且非零長度成員指向 URL 字串中適當的起點。儲存在 length 成員中的長度必須用來判斷個別元件資訊的結尾。

若要正確初始化 URL_COMPONENTS 結構， dwStructSize 成員必須設定為 URL_COMPONENTS 結構的大小。

建立 URL

WinHttpCreateUrl函式會使用先前描述URL_COMPONENTS結構中的資訊來建立 URL。

對於每個必要元件，指標成員應該包含保存資訊的緩衝區指標。如果指標成員包含以零結尾字串的指標，則長度成員應該設定為零;如果指標成員包含不是以零結尾的字串指標，則長度成員應該設定為字串長度。任何不需要之元件的指標成員都必須設定為 Null。

範例程式碼

下列範例程式碼示範如何使用WinHttpC，WinHttpCreateUrl來反組譯現有的 URL、修改其中一個元件，然後將它重新組譯成新的 URL。

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

共用方式為