UrlEscapeW 関数 (shlwapi.h)

インターネット経由での転送中に変更される可能性がある URL 内の文字またはサロゲート ペア ("unsafe" 文字) を対応するエスケープ シーケンスに変換します。 サロゲート ペアは、U+10000 から U+10FFFF (UTF-32 の場合) または DC00 から DFFF (UTF-16 の場合) の間の文字です。

構文

LWSTDAPI UrlEscapeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszEscaped,
  [in, out] DWORD  *pcchEscaped,
            DWORD  dwFlags
);

パラメーター

[in] pszUrl

種類: PCTSTR

dwFlags の値に応じて、完全または部分的な URL を含む最大長INTERNET_MAX_URL_LENGTHの null で終わる文字列。

[out] pszEscaped

種類: PTSTR

アンセーフ文字がエスケープ シーケンスに変換された、変換された文字列を受け取るバッファー。

[in, out] pcchEscaped

型: DWORD*

入力時に pszEscaped バッファー内の文字数を含む DWORD 値へのポインター。 UrlEscape を呼び出す前に、呼び出し元のアプリケーションは、pcchEscaped によって参照される値をバッファーのサイズに設定する必要があります。 この関数が正常に戻ると、値はバッファーに書き込まれた文字数を受け取りますが、終端の NULL 文字は含まれません。

E_POINTERエラー コードが返された場合、バッファーは小さすぎて結果を保持できません。 また、pcchEscaped によって参照される値はバッファー内の必要な文字数に設定されます。 他のエラーが返された場合、 pcchEscaped によって参照される値は未定義です。

dwFlags

型: DWORD

pszURL で指定されている URL の部分と、その文字列内のどの文字をエスケープ シーケンスに変換するかを示すフラグ。 次のフラグが定義されています。

URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)

URL_ESCAPE_SPACES_ONLY と組 み合わせて使用すると、クエリ内の文字 (文字列内で最初の # または ? 文字の後に続く URL の部分) が変換されないようにします。 このフラグは単独で使用したり、 URL_ESCAPE_SEGMENT_ONLYと組み合わせたりしないでください。

URL_BROWSER_MODE

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

URL_ESCAPE_SPACES_ONLY (0x04000000)

URL のクエリ部分のスペース文字を含め、スペース文字のみをエスケープ シーケンスに変換します。 その他の安全でない文字は、エスケープ シーケンスに変換されません。 このフラグは、 pszURL に完全な URL が含まれていないことを前提としています。 サーバー仕様に従う部分のみが必要です。

このフラグを URL_DONT_ESCAPE_EXTRA_INFO と組み合わせて、URL のクエリ部分の空白文字が変換されないようにします。

このフラグを URL_ESCAPE_PERCENT または URL_ESCAPE_SEGMENT_ONLYと組み合わせることはできません。

URL_ESCAPE_PERCENT (0x00001000)

URL のセグメント セクションで見つかった %文字 (サーバー仕様と最初の # または ? 文字の間にあるセクション) を変換します。 既定では、% 文字はエスケープ シーケンスに変換されません。 セグメント内の他の安全でない文字も正常に変換されます。

このフラグを URL_ESCAPE_SEGMENT_ONLY と組み合わせると、URL のクエリ部分にこれらの % 文字が含まれます。 ただし、 URL_ESCAPE_SEGMENT_ONLY フラグを指定すると、文字列全体がセグメント (任意の # または ? ) と見なされます。 文字も変換されます。

このフラグを URL_ESCAPE_SPACES_ONLYと組み合わせることはできません。

URL_ESCAPE_SEGMENT_ONLY (0x00002000)

pszURL に、サーバー コンポーネントの後のクエリの前にある URL のそのセクションのみが含まれていることを示します。 文字列内の安全でない文字はすべて変換されます。 このフラグを設定するときに完全な URL が指定されている場合、文字列全体の安全でない文字はすべて変換されます (# や ? の文字など)。

このフラグを URL_ESCAPE_PERCENT と組み合わせて、その文字を変換に含めます。

このフラグを URL_ESCAPE_SPACES_ONLY または URL_DONT_ESCAPE_EXTRA_INFOと組み合わせることはできません。

URL_ESCAPE_AS_UTF8 (0x00040000)

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

URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)

Windows 8 以降。 URI RFC 3986 (a-zA-Z0-9-.~_) から予約されていないセットの外部にあるすべての ASCII 文字をパーセントエンコードします。

戻り値

型: HRESULT

成功した場合はS_OKを返します。 pcchEscaped バッファーが小さすぎて結果を格納できなかった場合は、E_POINTERが返され、pcchEscaped が指す値が必要なバッファー サイズに設定されます。 それ以外の場合は、標準エラー値が返されます。

注釈

このドキュメントの目的上、一般的な URL は、サーバー、セグメント、クエリの 3 つのセクションに分かれています。 例:

http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment

サーバー部分は "http://microsoft.com/". 末尾のスラッシュは、サーバー部分の一部と見なされます。

セグメント部分は、サーバー部分の後にあるパスの任意の部分ですが、最初の # または ? の前にあります。 文字、この場合は単に "test.asp" です。

クエリ部分は、最初の # または ? からのパスの残りの部分です。 文字 (両端を含む)。 この例では、"?url=/example/abc.asp?frame=true#fragment" です。

安全でない文字は、インターネット経由で転送中に変更される可能性のある文字です。 この関数は、アンセーフ文字を同等の "%xy" エスケープ シーケンスに変換します。 次の表は、安全でない文字とそのエスケープ シーケンスを示しています。

URL_ESCAPE_SEGMENT_ONLY フラグを使用すると、 # (%23) の変換も発生します。 (%3F)、および / (%2F) 文字。

既定では、 UrlEscape は# または ? の後のテキストを無視します。 文字。 URL_ESCAPE_SEGMENT_ONLY フラグは、文字列全体をセグメントとして指定することで、この動作をオーバーライドします。 URL_ESCAPE_SPACES_ONLY フラグは、この動作をオーバーライドしますが、スペース文字の場合のみオーバーライドします。

例

次の例は、URL に対するさまざまなフラグの効果を示しています。 URL の例は無効ですが、デモ目的で誇張されています。

// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment    

// URL_ESCAPE_SPACES_ONLY 
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query 
//       components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result   = test%2Ft%e%3Cs%20t.asp

要件

こちらもご覧ください

Uniform Resource Locator の処理