GetShortPathNameW 関数 (fileapi.h)

[アーティクル]
10/05/2022

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

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

構文

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

パラメーター

[in] lpszLongPath

パス文字列。

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

[out] lpszShortPath

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

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

[in] cchBuffer

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

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)	いいえ
SMB 3.0 とスケールアウトファイル共有 (SO)	いいえ
クラスター共有ボリュームファイルシステム (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)

構文

パラメーター

戻り値

解説

例

要件

関連項目

その他のリソース

その他のリソース