GetShortPathNameW 関数 (fileapi.h)

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

指定したパスの短いパス形式を取得します。

ファイル名とパス名の詳細については、「名前付けファイル、パス、および名前空間」を参照してください。

構文

DWORD GetShortPathNameW(
  [in]  LPCWSTR lpszLongPath,
  [out] LPWSTR  lpszShortPath,
  [in]  DWORD   cchBuffer
);

パラメーター

[in] lpszLongPath

パス文字列。

既定では、名前はMAX_PATH文字に制限されています。この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。詳細については、「名前付けファイル、パス、および名前空間」の「パスの最大長制限」セクションを参照してください。

[out] lpszShortPath

lpszLongPath が指定するパスの null で終わる短い形式を受け取るバッファーへのポインター。

このパラメーターに NULL を渡し、 cchBuffer に 0 を渡すと、指定した lpszLongPath に必要なバッファーサイズが常に返されます。

[in] cchBuffer

TCHAR の lpszShortPath が指すバッファーのサイズ。

lpszShortPath が NULL に設定されている場合は、このパラメーターを 0 に設定します。

戻り値

関数が成功した場合、戻り値は lpszShortPath にコピーされる文字列の長さ (TCHAR) であり、終端の null 文字は含まれません。

lpszShortPath バッファーが小さすぎてパスを格納できない場合、戻り値は、パスと終端の null 文字を保持するために必要なバッファーのサイズ (TCHAR) です。

その他の理由で関数が失敗した場合、戻り値は 0 になります。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

lpszLongPath パラメーターが指定するパスは、完全パスまたは長いパスである必要はありません。短い形式は、指定したパスよりも長くすることができます。

戻り値が cchBuffer パラメーターで指定された値より大きい場合は、パスを保持するのに十分な大きさのバッファーを使用して関数を再度呼び出すことができます。動的割り当てに長さ 0 のバッファーを使用するだけでなく、この場合の例については、「コード例」セクションを参照してください。

メモこの場合の戻り値は終端の null 文字を含む長さですが、成功した場合の戻り値にはカウントに終端の null 文字は含まれません。

指定したパスが既に短い形式で、変換が不要な場合、関数は指定したパスを lpszShortPath パラメーターで指定されたバッファーにコピーします。

lpszShortPath パラメーターを lpszLongPath パラメーターと同じ値に設定できます。つまり、短いパスの出力バッファーを入力パス文字列のアドレスに設定できます。 cchBuffer パラメーターが、このバッファーの合計サイズ (TCHAR) を正確に表していることを常に確認してください。

GetLongPathName 関数を呼び出すことで、短い名前からファイルの長い名前を取得できます。または、 GetLongPathName が使用できない場合は、パスの各コンポーネントで FindFirstFile を呼び出して、対応する長い名前を取得できます。

ファイルまたはディレクトリにアクセスできますが、そのファイルまたはディレクトリの親ディレクトリの一部にはアクセスできません。その結果、パスコンポーネントの親ディレクトリに対してクエリを実行して、そのコンポーネントの短い名前を判断できない場合、 GetShortPathName が失敗する可能性があります。このチェックは、短い名前の要件を既に満たしているディレクトリコンポーネントではスキップできます。詳細については、「名前付けファイル、パス、および名前空間」の「短い名前と長い名前」セクションを参照してください。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ	サポートされています
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 Transparent Failover (TFO)	いいえ
スケールアウトファイル共有 (SO) を使う SMB 3.0	いいえ
クラスターの共有ボリュームファイルシステム (CsvFS)	いいえ
Resilient File System (ReFS)	はい

SMB 3.0 では、継続的な可用性機能を備えた共有の短い名前はサポートされていません。

回復性のあるファイルシステム (ReFS) では、短い名前はサポートされていません。ディスク上に短い名前がないパスで GetShortPathName を 呼び出すと、呼び出しは成功しますが、代わりに長い名前のパスが返されます。この結果は、指定された長い名前に短い名前が存在する保証がないため、NTFS ボリュームでも可能です。

例

GetShortPathName を使用する例については、「GetFullPathName のコード例」セクションを参照してください。

次の C++ の例は、動的に割り当てられた出力バッファーを使用する方法を示しています。

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	fileapi.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

GetShortPathNameW 関数 (fileapi.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース