Função GetFileTitleA (commdlg.h)

Artigo
11/20/2024

Recupera o nome do arquivo especificado.

Sintaxe

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

Parâmetros

[in] unnamedParam1

Tipo: LPCTSTR

O nome e o local de um arquivo.

[out] Buf

Tipo: LPTSTR

O buffer que recebe o nome do arquivo.

[in] cchSize

Tipo: word

O comprimento, em caracteres, do buffer apontado pelo parâmetro lpszTitle.

Valor de retorno

Tipo: curto

Se a função for bem-sucedida, o valor retornado será zero.

Se o nome do arquivo for inválido, o valor retornado será desconhecido. Se houver um erro, o valor retornado será um número negativo.

Se o buffer apontado pelo parâmetro lpszTitle for muito pequeno, o valor retornado será um inteiro positivo que especifica o tamanho do buffer necessário, em caracteres. O tamanho do buffer necessário inclui o caractere nulo de encerramento.

Observações

GetFileTitle só deve ser chamado com nomes de arquivo legais; usar um nome de arquivo ilegal tem um resultado indefinido.

Para obter o tamanho do buffer necessário para o nome de um arquivo, chame a função com lpszTitle definido como NULL e cchSize definido como zero. A função retorna o tamanho necessário.

GetFileTitle retorna a cadeia de caracteres que o sistema usaria para exibir o nome do arquivo para o usuário. O nome de exibição inclui uma extensão somente se essa for a preferência do usuário para exibir nomes de arquivo. Isso significa que a cadeia de caracteres retornada pode não identificar com precisão o arquivo se ele for usado em chamadas para funções do sistema de arquivos.

Se o buffer lpszTitle for muito pequeno, GetFileTitle retornará o tamanho necessário para manter o nome de exibição. No entanto, não há nenhuma relação garantida entre o tamanho necessário e os caracteres especificados originalmente no buffer lpszFile . Por exemplo, não chame GetFileTitle com lpszTitle definidos como NULL e cchSize definido como zero e tente usar o valor retornado como um índice na cadeia de caracteres lpszFile. Normalmente, você pode obter resultados semelhantes (e desempenho superior) com funções de biblioteca em tempo de execução C, como strrchr, wcsrchre _mbsrchr.

Nota

O cabeçalho commdlg.h define GetFileTitle como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	commdlg.h (inclua Windows.h)
biblioteca	Comdlg32.lib
de DLL	Comdlg32.dll
conjunto de API	ext-ms-win-shell-comdlg32-l1-1-1 (introduzido no Windows 10, versão 10.0.14393)

Consulte também

da Biblioteca de Caixas de Diálogo Comuns

Conceitual

GetOpenFileName

GetSaveFileName

de referência de

Compartilhar via