UrlEscapeW 関数 (shlwapi.h)

[アーティクル]
03/02/2024

インターネット経由での転送中に変更される可能性がある 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" エスケープシーケンスに変換します。次の表は、安全でない文字とそのエスケープシーケンスを示しています。

文字	エスケープシーケンス
^	%5E
&	%26
`	%60
{	%7B
}	%7D
\|	%7C
]	%5D
[	%5B
"	%22
<	%3C
>	%3E
\	%5C

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

注意

shlwapi.h ヘッダーは、URLEscape をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional、Windows XP [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	shlwapi.h
Library	Shlwapi.lib
[DLL]	Shlwapi.dll (バージョン 5.0 以降)

こちらもご覧ください

Uniform Resource Locator の処理

次の方法で共有