UrlCanonicalizeW 関数 (shlwapi.h)

URL 文字列を正規フォームに変換します。

構文

LWSTDAPI UrlCanonicalizeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszCanonicalized,
  [in, out] DWORD  *pcchCanonicalized,
            DWORD  dwFlags
);

パラメーター

[in] pszUrl

種類: PCTSTR

URL 文字列を含む最大長INTERNET_MAX_URL_LENGTHの null で終わる文字列へのポインター。 文字列がファイルを参照しない場合、"http://" のような有効なスキームが含まれている必要があります。

[out] pszCanonicalized

種類: PTSTR

この関数が正常に返されるときに、変換された URL を null で終わる文字列として受け取るバッファーへのポインター。

[in, out] pcchCanonicalized

型: DWORD*

エントリ時に pszCanonicalized バッファー内の文字数に設定される値へのポインター。

dwFlags

型: DWORD

URL を正規形式に変換する方法を指定するフラグ。 次のフラグを組み合わせることができます。

URL_UNESCAPE (0x10000000)

2 つの例外を含む、URL に含まれるエスケープ シーケンスのエスケープを解除します。 "?" と "#" のエスケープ シーケンスのエスケープは解除されません。 URL_ESCAPE_XXX フラグの 1 つが設定されている場合、2 つの URL は最初にエスケープ解除され、次に結合されてからエスケープされます。

URL_ESCAPE_UNSAFE (0x20000000)

安全でない文字をそのエスケープ シーケンスに置換します。 安全でない文字は、インターネット経由で転送中に変更される可能性のある文字であり、(<、、"、 >#、{、}、|、、^、[、]、および ') 文字が含まれます。 このフラグは、あいまいな URL を含む、すべての URL に適用されます。

URL_PLUGGABLE_PROTOCOL (0x40000000)

W3C 仕様に従って、URL とクライアント定義のプラグ可能なプロトコルを組み合わせます。 このフラグは、FTP、HTTP、Gopher など、標準のプロトコルには適用されません。 このフラグが設定されている場合、 UrlCombine は URL を簡略化しないため、 URL_DONT_SIMPLIFYも設定する必要はありません。

URL_ESCAPE_SPACES_ONLY (0x04000000)

スペースだけをエスケープ シーケンスで置換します。 このフラグは URL_ESCAPE_UNSAFEよりも優先されますが、不透明な URL には適用されません。

URL_DONT_SIMPLIFY (0x08000000)

URL 文字列内の "/./" と "/../" を、ナビゲーションのための短縮形としてではなく、リテラル文字列として処理します。 詳細については、「解説」を参照してください。

URL_NO_META (0x08000000)

URL_DONT_SIMPLIFYと同じに定義されます。

URL_ESCAPE_PERCENT (0x00001000)

"%" が現れた場合、それをそのエスケープ シーケンスに変換します。

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 以降。 すべての非 ASCII 文字を UTF-8 に相当するものとしてパーセントエンコードします。

戻り値

型: HRESULT

この関数が成功すると、 S_OKが返されます。 そうでない場合は、HRESULT エラー コードを返します。

注釈

この関数は、アンセーフ文字をエスケープ シーケンスに置き換えたり、"....." などのシーケンスを折りたたむなどのタスクを実行します。

URL 文字列に "/.. が含まれている場合。/" または "/./"、 UrlCanonicalize は、URL 階層のナビゲーションを示す文字として扱います。 関数は、URL を組み合わせる前に簡略化します。 たとえば、"/hello/cruel/../world" は "/hello/world" に簡略化されています。 この既定の動作の例外は、次の場合に発生します。

• URL_DONT_SIMPLIFY フラグが dwFlags で設定されている場合、関数は URL を簡略化しません。 この場合は、"/hello/cruel/../world" はそのままです。
• "/../" または "/./" はパス内の最初のセグメント ("http://domain/../path1/path2/file.htm"など) です。 UrlCanonicalize は、パスが入力されたとおりに出力されます。

要件

こちらもご覧ください

Uniform Resource Locator の処理