InternetCanonicalizeUrlA 関数 (wininet.h)

  • [アーティクル]

URL を正規化します。これには、安全でない文字や空白をエスケープ シーケンスに変換する処理が含まれます。

構文

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

パラメーター

[in] lpszUrl

正規化する URL を含む文字列へのポインター。

[out] lpszBuffer

結果として得られる正規化された URL を受け取るバッファーへのポインター。

[in, out] lpdwBufferLength

lpszBuffer バッファーのサイズ (文字単位) を含む変数へのポインター。 関数が成功した場合、このパラメーターは lpszBuffer バッファーに実際にコピーされた文字数を受け取りますが、終端の null 文字は含まれません。 関数が失敗した場合、このパラメーターはバッファーの必要なサイズを文字単位で受け取ります。これには、終端の null 文字が含まれます。

[in] dwFlags

正規化を制御します。 フラグが指定されていない場合、関数はすべての安全でない文字とメタ シーケンス (.,\ ..、..など) をエスケープ シーケンスに変換します。 このパラメーターには、次の値のいずれかを指定できます。

値 説明
ICU_BROWSER_MODE
 "#" または "?"" の後に文字をエンコードまたはデコードせず、末尾の空白を "?" の後に削除しません。 この値を指定しない場合、URL 全体がエンコードされ、末尾の空白は削除されます。
ICU_DECODE
 URL が解析される前に、すべての %XX シーケンスをエスケープ シーケンスを含む文字に変換します。
ICU_ENCODE_PERCENT
 検出されたパーセント記号をエンコードします。 既定では、パーセント記号はエンコードされません。 この値は、Microsoft Internet エクスプローラー 5 以降で使用できます。
ICU_ENCODE_SPACES_ONLY
 スペースのみをエンコードします。
ICU_NO_ENCODE
 安全でない文字をエスケープ シーケンスに変換しません。
ICU_NO_META
 URL からメタ シーケンス ("." や ".." など) を削除しません。

戻り値

成功した場合は TRUE 、それ以外の場合 は FALSE を 返します。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。 考えられるエラーは次のとおりです。

リターン コード 説明
ERROR_BAD_PATHNAME
 URL を正規化できませんでした。
ERROR_INSUFFICIENT_BUFFER
 正規化された URL が大きすぎて、指定されたバッファーに収まりません。 lpdwBufferLength パラメーターは、正規化された URL を保持するために必要なバッファーのサイズ (バイト単位) に設定されます。
ERROR_INTERNET_INVALID_URL
 URL の形式が無効です。
ERROR_INVALID_PARAMETER
 無効な文字列、バッファー、バッファー サイズ、または flags パラメーターがあります。

解説

Internet エクスプローラー 4.0 以降では、InternetCanonicalizeUrl は常に ICU_BROWSER_MODE フラグが設定されているかのように機能します。 URL 全体を正規化する必要があるクライアント アプリケーションでは、 CoInternetParseUrl (アクション がPARSE_CANONICALIZE され、フラグ がURL_ESCAPE_UNSAFE) または UrlCanonicalize を使用する必要があります。

InternetCanonicalizeUrl は、 ICU_DECODE フラグが指定されている場合でも、常に既定でエンコードされます。 再エンコードせずにデコードするには、ICU_DECODE ICU_NO_ENCODE | を使用します。 ICU_DECODE フラグがICU_NO_ENCODEなしで使用される場合、URL は解析される前にデコードされます。解析後、安全でない文字が再エンコードされます。 この関数は任意のプロトコル スキームを処理しますが、これを行うには、安全でない文字セットから推論を行う必要があります。

Internet エクスプローラー 3.0 を使用する場合 (またはインターネット エクスプローラー 5 以降のICU_ENCODE_PERCENT フラグを設定する場合) に InternetCanonicalizeUrl を呼び出すアプリケーションは、特定の URL でこの関数の使用状況を追跡する必要があります。 URL 内の安全でない文字がエスケープ シーケンスに変換されている場合、 URL で InternetCanonicalizeUrl をもう一度使用すると (フラグなし)、エスケープ シーケンスが別のエスケープ シーケンスに変換されます。 たとえば、URL 内の空白はエスケープ シーケンス %20 に変換されます。 URL で InternetCanonicalizeUrl を 再度呼び出すと、エスケープ シーケンス %20 がエスケープ シーケンス %2520 に変換されます。これは、% 記号がエスケープ シーケンス用に予約され、関数によってエスケープ シーケンス %25 に置き換えられる安全でない文字であるためです。

WinINet API の他のすべての側面と同様に、この関数を DllMain またはグローバル オブジェクトのコンストラクターとデストラクター内から安全に呼び出すことはできません。

メモ WinINet では、サーバーの実装はサポートされていません。 また、サービスから使用しないでください。 サーバーの実装またはサービスの場合は、 Microsoft Windows HTTP サービス (WinHTTP) を使用します。
 

Note

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

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー wininet.h
Library Wininet.lib
[DLL] Wininet.dll

関連項目

一様リソース ロケーターの処理

WinINet 関数