PathCchCanonicalizeEx 関数 (pathcch.h)

  • [アーティクル]

"." や ".." などのナビゲーション要素を削除して、直接の適切な形式のパスを生成することで、パスを簡略化します。

この関数は PathCchCanonicalize とは異なり、より長い最終パスを構築できる点で異なります。

この関数は、呼び出し元がスタックに格納されている返される文字列のサイズを宣言する必要がある点で、 PathAllocCanonicalize とは異なります。

この関数は PathCanonicalize とは異なり、"\"、"\?" および "\?\UNC" プレフィックスを持つパスを受け入れます。

メモ この関数 PathCchCanonicalize、または PathAllocCanonicalize は、バッファー オーバーランの可能性を防ぐために PathCanonicalize の代わりに使用する必要があります。

構文

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

パラメーター

[out] pszPathOut

この関数が正常に返されると、編集されたパス文字列を受け取るバッファーへのポインター。

[in] cchPathOut

pszPathOut が指すバッファーのサイズ (文字数)。

[in] pszPathIn

元のパス文字列へのポインター。 この値が NULL の場合、空の文字列を指すか、"." 要素と ".." 要素が削除されると空の文字列になります。 pszPathOut が指すバッファーに 1 つの円記号がコピーされます。

[in] dwFlags

次のフラグの 1 つまたは複数:

値 意味
PATHCCH_NONE
0x0000000
 \\?\ パス (つまり、長いパス) を MAX_PATH より長く構築することはできません。
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 を超える \\?\ パスの構築 MAX_PATH 許可します。 cchPathOut は MAX_PATH より大きくする必要があることに注意してください。 そうでない場合、このフラグは無視されます。
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 プロセスの長い名前が有効な状態とは関係なく、呼び出し元を長いパスが有効として処理するように API に強制します。 このオプションは、 PATHCCH_ALLOW_LONG_PATHS が指定されている場合にのみ使用でき、 PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESSでは使用できません。

メモこの値は、Windows 10 バージョン 1703 以降で使用できます。
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 プロセスの長い名前が有効な状態とは関係なく、呼び出し元を長いパスが無効として API に強制的に処理します。 このオプションは、 PATHCCH_ALLOW_LONG_PATHS が指定されている場合にのみ使用でき、 PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESSでは使用できません。

メモこの値は、Windows 10 バージョン 1703 以降で使用できます。
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 末尾のドットとスペースの削除を含むパス セグメントの正規化を無効にします。 これにより、win32 パス正規化がブロックするパスへのアクセスが可能になります。

メモこの値は、Windows 10 バージョン 1703 以降で使用できます。
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 入力パスを拡張長 DOS デバイス パス フォーム (\\?\ プレフィックス付き) に変換します (まだその形式でない場合)。 これにより、Win32 正規化規則 (末尾のドットとスペースを削除できる) とパスの長さの制限により、アドレス指定できないパスにアクセスできます。 このオプションは、PATHCCH_DO_NOT_NORMALIZE_SEGMENTSと同じ動作を意味 します。

メモこの値は、Windows 10 バージョン 1703 以降で使用できます。
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 パスを結合または正規化する場合は、末尾に円記号があることを確認します。

メモこの値は、Windows 10 バージョン 1703 以降で使用できます。

戻り値

この関数が成功すると、 S_OKが返されます。 それ以外の場合は、次を含むがこれらに限定されない HRESULT コードが返されます。

リターン コード 説明
E_INVALIDARG
 cchPathOut 値がPATHCCH_MAX_CCHより大きい。
PATHCCH_E_FILENAME_TOO_LONG
 パス セグメントの文字数が PATHCCH_MAX_CCH 文字を超える場合、または PATHCCH_ALLOW_LONG_PATHS フラグが設定されていない場合は、標準パス セグメントの長さの制限である 256 文字を超えています。
E_OUTOFMEMORY
 関数は、必要なサイズのバッファーを割り当てませんでした。

注釈

この関数は、パスに埋め込まれた文字列 "." と "." に応答します。 ".." 文字列は、直前のパス セグメントを削除することを示します。 "." 文字列は、次のパス セグメントをスキップすることを示します。 パスのルート セグメントを削除できないことに注意してください。 パス セグメントよりも多くの ".." 文字列がある場合、関数は S_OK を返し、 pszPathOut が指すバッファーには単一の円記号 "\" が含まれます。

"" のワイルドなカード文字が前にある場合を除き、末尾のすべてのピリオドがパスから削除されます。その場合、1 つのピリオドは '' 文字の後に保持されますが、それ以外のすべての末尾のピリオドは削除されます。

結果のパスがルート ドライブ ("x:") の場合は、円記号 ("x:\") が追加されます。

この関数は、スラッシュ (/) をバック スラッシュ (\) に変換しません。 信頼されていない入力では、この関数自体を使用して、パスをサブパスまたは ID の他のパスと比較できるフォームに変換することはできません。 その機能を必要とする呼び出し元は、この関数を使用する前にバック スラッシュに変換する必要があります。

次の例は、これらの文字列の効果を示しています。

元の文字列 正規化された文字列
C:\name_1\.\name_2\..\name_3 C:\name_1\name_3
C:\name_1\..\name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\..\name_4 C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\..\name_4\.. C:\name_1\name_2
C:\name_1\*... C:\name_1\*。
C：\。。 C:\

要件

要件 値
サポートされている最小のクライアント Windows 8 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2012 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー pathcch.h
Library Pathcch.lib

こちらもご覧ください

PathCchCanonicalize