Функция GetFileTitleA (commdlg.h)

Статья
08/22/2023

Извлекает имя указанного файла.

Синтаксис

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

Параметры

[in] unnamedParam1

Тип: LPCTSTR

Имя и расположение файла.

[out] Buf

Тип: LPTSTR

Буфер, получающий имя файла.

[in] cchSize

Тип: WORD

Длина буфера в символах, на который указывает параметр lpszTitle .

Возвращаемое значение

Тип: short

Если вызов функции заканчивается удачно, возвращается нулевое значение.

Если имя файла недопустимо, возвращаемое значение неизвестно. Если возникает ошибка, возвращаемое значение является отрицательным числом.

Если буфер, на который указывает параметр lpszTitle , слишком мал, возвращаемое значение представляет собой положительное целое число, указывающее требуемый размер буфера в символах. Требуемый размер буфера включает завершающий символ NULL.

Чтобы получить размер буфера, необходимый для имени файла, вызовите функцию с параметром lpszTitle , равным NULL , а для параметра cchSize — нулевое значение. Функция возвращает необходимый размер.

GetFileTitle возвращает строку, которую система будет использовать для отображения имени файла пользователю. Отображаемое имя включает расширение только в том случае, если это предпочтительный вариант для отображения имен файлов. Это означает, что возвращаемая строка может не точно идентифицировать файл, если он используется в вызовах функций файловой системы.

Если буфер lpszTitle слишком мал, GetFileTitle возвращает размер, необходимый для хранения отображаемого имени. Однако между требуемым размером и символами, изначально указанными в буфере lpszFile , нет гарантированной связи. Например, не вызывайте GetFileTitle с параметром lpszTitle , имеющим значение NULL , а cchSize — нулевое, а затем попробуйте использовать возвращаемое значение в качестве индекса в строке lpszFile . Как правило, аналогичные результаты (и более высокую производительность) можно достичь с помощью функций библиотеки времени выполнения C, таких как strrchr, wcsrchr и _mbsrchr.

Примечание

Заголовок commdlg.h определяет GetFileTitle как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	commdlg.h (включая Windows.h)
Библиотека	Comdlg32.lib
DLL	Comdlg32.dll
Набор API	ext-ms-win-shell-comdlg32-l1-1-1 (появилось в Windows 10, версия 10.0.14393)