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 を解読する前に、有効性または正しい形式をチェックしません。

[in] dwUrlLength

pwszUrl 文字列の長さ (文字数)。 dwUrlLength が 0 に設定されている場合、WinHttpCrackUrl は pwszUrl 文字列が null 終了であると見なし、その前提に基づいて pwszUrl 文字列の長さを決定します。

[in] dwFlags

操作を制御するフラグ。 このパラメーターには、次のフラグの 1 つ以上を組み合わせて指定できます (値はビット単位で OR を組み合わせて使用できます)。 または、特別な操作を実行しない 0 パラメーターを指定できます。

[in, out] lpUrlComponents

URL コンポーネントを受け取る URL_COMPONENTS 構造体へのポインター。

戻り値

関数が成功した場合は TRUE 、それ以外の場合 は FALSE を 返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 返されるエラー コードの中には、次のエラー コードがあります。

解説

WinHTTP が非同期モードで使用されている場合 (つまり、WinHttpOpen でWINHTTP_FLAG_ASYNCが設定されている場合)、この関数は同期的に動作します。 戻り値は、成功または失敗を示します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

必要なコンポーネントは、 URL_COMPONENTS 構造体のメンバーによって示されます。 各コンポーネントには、値へのポインターがあり、格納されている値の長さを格納するメンバーがあります。 コンポーネントの値と長さの両方が 0 に等しい場合、そのコンポーネントは返されません。 コンポーネントの値へのポインターが NULL ではなく、対応する長さメンバーの値が 0 以外の場合、 pwszUrl 文字列内の対応するコンポーネントの最初の文字のアドレスがポインターに格納され、コンポーネントの長さが長さメンバーに格納されます。

ポインターにユーザー指定のバッファーのアドレスが含まれている場合、長さメンバーにはバッファーのサイズが含まれている必要があります。 WinHttpCrackUrl 関数は、コンポーネントをバッファーにコピーし、length メンバーはコピーしたコンポーネントの長さ (末尾の文字列ターミネータの場合は 1 を引いた値) に設定されます。 ユーザーが指定したバッファーの大きさが十分でない場合、WinHttpCrackUrl は FALSE を返し、GetLastError はERROR_INSUFFICIENT_BUFFERを返します。

WinHttpCrackUrl が正常に機能するためには、URL_COMPONENTS構造体のサイズを、その構造体の dwStructSize メンバーに格納する必要があります。

pwszUrl に渡される URL のインターネット プロトコルが HTTP または HTTPS ではない場合、WinHttpCrackUrl は FALSE を返し、GetLastError は を示します
ERROR_WINHTTP_UNRECOGNIZED_SCHEME。

WinHttpCrackUrl では、URL を解読する前に URL の有効性や形式がチェックされません。 その結果、""http://server?Bad=URL"" などの文字列が渡されると、関数は正しくない結果を返します。

例

この例では、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;
    }

要件

関連項目

Microsoft Windows HTTP サービス (WinHTTP) について

一様リソース ロケーターの処理

WinHTTP バージョン

WinHttpCreateUrl