Funzione GetShortPathNameW (fileapi.h)

Articolo
03/13/2024

Recupera il formato di percorso breve del percorso specificato.

Per altre informazioni sui nomi di file e percorsi, vedere Denominazione di file, percorsi e spazi dei nomi.

Sintassi

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

Parametri

[in] lpszLongPath

Stringa di percorso.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, anteporre "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

Suggerimento

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente a rimuovere la limitazione MAX_PATH senza anteporre "\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, percorsi e spazi dei nomi .

[out] lpszShortPath

Puntatore a un buffer per ricevere la forma breve con terminazione Null del percorso specificato da lpszLongPath .

Passando NULL per questo parametro e zero per cchBuffer restituirà sempre le dimensioni del buffer necessarie per un lpszLongPath specificato.

[in] cchBuffer

Dimensioni del buffer a cui punta lpszShortPath , in TCHAR.

Impostare questo parametro su zero se lpszShortPath è impostato su NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la lunghezza, in TCHARs, della stringa copiata in lpszShortPath, senza includere il carattere null di terminazione.

Se il buffer lpszShortPath è troppo piccolo per contenere il percorso, il valore restituito è la dimensione del buffer, in TCHAR, che deve contenere il percorso e il carattere null di terminazione.

Se la funzione ha esito negativo per qualsiasi altro motivo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il percorso specificato dal parametro lpszLongPath non deve essere un percorso completo o lungo. La forma breve può essere più lunga del percorso specificato.

Se il valore restituito è maggiore del valore specificato nel parametro cchBuffer , è possibile chiamare di nuovo la funzione con un buffer sufficientemente grande da contenere il percorso. Per un esempio di questo caso oltre all'uso del buffer di lunghezza zero per l'allocazione dinamica, vedere la sezione Codice di esempio.

Nota Anche se il valore restituito in questo caso è una lunghezza che include il carattere Null di terminazione, il valore restituito in caso di esito positivo non include il carattere null di terminazione nel conteggio.

Se il percorso specificato è già in forma breve e la conversione non è necessaria, la funzione copia semplicemente il percorso specificato nel buffer specificato dal parametro lpszShortPath .

È possibile impostare il parametro lpszShortPath sullo stesso valore del parametro lpszLongPath ; in altre parole, è possibile impostare il buffer di output per il percorso breve all'indirizzo della stringa del percorso di input. Assicurarsi sempre che il parametro cchBuffer rappresenti in modo accurato le dimensioni totali, in TCHAR, di questo buffer.

È possibile ottenere il nome lungo di un file dal nome breve chiamando la funzione GetLongPathName . In alternativa, dove GetLongPathName non è disponibile, è possibile chiamare FindFirstFile in ogni componente del percorso per ottenere il nome lungo corrispondente.

È possibile avere accesso a un file o a una directory, ma non avere accesso ad alcune delle directory padre di tale file o directory. Di conseguenza, GetShortPathName potrebbe non riuscire quando non è in grado di eseguire una query sulla directory padre di un componente del percorso per determinare il nome breve per tale componente. Questo controllo può essere ignorato per i componenti di directory che soddisfano già i requisiti di un nome breve. Per altre informazioni, vedere la sezione Nomi brevi e lunghi di Denominazione di file, percorsi e spazi dei nomi.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	No
SMB 3.0 con condivisioni file di scalabilità orizzontale (SO)	No
File system del volume condiviso cluster (CsvFS)	No
Resilient File System (ReFS)	Sì

SMB 3.0 non supporta nomi brevi nelle condivisioni con funzionalità di disponibilità continua.

Resilient File System (ReFS) non supporta nomi brevi. Se si chiama GetShortPathName in un percorso che non contiene nomi brevi su disco, la chiamata avrà esito positivo, ma restituirà invece il percorso con nome lungo. Questo risultato è anche possibile con i volumi NTFS perché non esiste alcuna garanzia che esista un nome breve per un determinato nome lungo.

Esempio

Per un esempio che usa GetShortPathName, vedere la sezione Codice di esempio per GetFullPathName.

L'esempio C++ seguente illustra come usare un buffer di output allocato in modo dinamico.

//...
    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;
///...

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll