UrlEscapeA 関数 (shlwapi.h)
インターネット経由での転送中に変更される可能性がある URL 内の文字またはサロゲート ペア ("unsafe" 文字) を対応するエスケープ シーケンスに変換します。 サロゲート ペアは、U+10000 から U+10FFFF (UTF-32 の場合) または DC00 から DFFF (UTF-16 の場合) の間の文字です。
構文
LWSTDAPI UrlEscapeA(
[in] PCSTR pszUrl,
[out] PSTR 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 以降) |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示