Funzione GetFileTitleA (commdlg.h)

Articolo
02/24/2024

Recupera il nome del file specificato.

Sintassi

short GetFileTitleA(
  [in]  LPCSTR unnamedParam1,
  [out] LPSTR  Buf,
  [in]  WORD   cchSize
);

Parametri

[in] unnamedParam1

Tipo: LPCTSTR

Nome e percorso di un file.

[out] Buf

Tipo: LPTSTR

Buffer che riceve il nome del file.

[in] cchSize

Tipo: WORD

Lunghezza, in caratteri, del buffer a cui punta il parametro lpszTitle .

Valore restituito

Tipo: short

Se la funzione ha esito positivo, il valore restituito è zero.

Se il nome del file non è valido, il valore restituito è sconosciuto. Se si verifica un errore, il valore restituito è un numero negativo.

Se il buffer a cui punta il parametro lpszTitle è troppo piccolo, il valore restituito è un numero intero positivo che specifica le dimensioni del buffer necessarie, in caratteri. Le dimensioni del buffer necessarie includono il carattere Null di terminazione.

Commenti

GetFileTitle deve essere chiamato solo con nomi di file legali; l'uso di un nome file non valido ha un risultato non definito.

Per ottenere le dimensioni del buffer necessarie per il nome di un file, chiamare la funzione con lpszTitle impostato su NULL e cchSize impostato su zero. La funzione restituisce le dimensioni necessarie.

GetFileTitle restituisce la stringa usata dal sistema per visualizzare il nome del file all'utente. Il nome visualizzato include un'estensione solo se si tratta della preferenza dell'utente per la visualizzazione dei nomi di file. Ciò significa che la stringa restituita potrebbe non identificare accuratamente il file se viene usato nelle chiamate alle funzioni del file system.

Se il buffer lpszTitle è troppo piccolo, GetFileTitle restituisce le dimensioni necessarie per contenere il nome visualizzato. Tuttavia, non esiste alcuna relazione garantita tra le dimensioni richieste e i caratteri originariamente specificati nel buffer lpszFile . Ad esempio, non chiamare GetFileTitle con lpszTitle impostato su NULL e cchSize impostato su zero e quindi provare a usare il valore restituito come indice nella stringa lpszFile . In genere è possibile ottenere risultati simili (e prestazioni superiori) con funzioni della libreria di runtime C, ad esempio strrchr, wcsrchr e _mbsrchr.

Nota

L'intestazione commdlg.h definisce GetFileTitle come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	commdlg.h (include Windows.h)
Libreria	Comdlg32.lib
DLL	Comdlg32.dll
Set di API	ext-ms-win-shell-comdlg32-l1-1-1 (introdotto in Windows 10, versione 10.0.14393)