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 パラメーターを指定できます。

値 説明
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 構造体のメンバーによって示されます。 各コンポーネントには、値へのポインターがあり、格納されている値の長さを格納するメンバーがあります。 コンポーネントの値と長さの両方が 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"" などの文字列が渡されると、関数は正しくない結果を返します。

メモ 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 およびインターネット エクスプローラー 5.01 以降。

関連項目

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

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

WinHTTP バージョン

WinHttpCreateUrl