WinHttpCrackUrl 関数 (winhttp.h)

[アーティクル]
08/27/2023

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 以降。

次の方法で共有

WinHttpCrackUrl 関数 (winhttp.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

その他のリソース