UrlEscapeA 関数 (shlwapi.h)

[アーティクル]
11/20/2024

インターネット経由の転送中に変更される可能性がある 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*

dWORD 値へのポインター。エントリには、pszEscaped バッファー内の文字数が含まれます。 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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして UrlEscape を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

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

次の方法で共有