Função PathAddExtensionW (shlwapi.h)

Adiciona uma extensão de nome de arquivo a uma cadeia de caracteres de caminho.

Observação Uso indevido dessa função pode levar a uma sobrecarga de buffer. Recomendamos o uso da função PathCchAddExtension mais segura em seu lugar.

 

Sintaxe

BOOL PathAddExtensionW(
  [in, out]      LPWSTR  pszPath,
  [in, optional] LPCWSTR pszExt
);

Parâmetros

[in, out] pszPath

Tipo: LPTSTR

Um ponteiro para um buffer com a cadeia de caracteres terminada em nulo à qual a extensão de nome de arquivo será acrescentada. Você deve definir o tamanho desse buffer para MAX_PATH para garantir que ele seja grande o suficiente para manter a cadeia de caracteres retornada.

[in, optional] pszExt

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém a extensão de nome de arquivo. Esse valor pode ser NULL.

Valor de retorno

Tipo: BOOL

Retorna verdadeiro se uma extensão foi adicionada ou false caso contrário.

Observações

Se já houver uma extensão de nome de arquivo presente, nenhuma extensão será adicionada. Se o pszPath apontar para uma cadeia de NULL , o resultado será apenas a extensão de nome de arquivo. Se pszExtension apontar para uma cadeia de caracteres NULL , uma extensão ".exe" será adicionada.

Exemplos

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
     // String for path name without file name extension.
     char buffer_1[MAX_PATH] = "file";
     char *lpStr1;
     lpStr1 = buffer_1;

     // String for path name with file name extension.
     char buffer_2[ ] = "file.doc";
     char *lpStr2;
     lpStr2 = buffer_2;

     // String for extension name.
     char F_Ext[MAX_PATH] = ".txt";
     char *lpStr3;
     lpStr3 = F_Ext;

     // Null string as path. 
     char N_String[MAX_PATH] = "\0";
     char *lpStr4;
     lpStr4 = N_String;

     // Path 1 without the file name extension.
     cout << "The original path string 1 is  " << lpStr1 << endl;

     int ret_1 = PathAddExtension(lpStr1,lpStr3);
     cout << "The modified path string 1 is  " << lpStr1 << endl;

    // Path 2 with the file name extension already there.
    cout << "The original path string 2 is  " << lpStr2 << endl;
    int ret_2 = PathAddExtension(lpStr2,lpStr3);
    cout << "The modified path string 2 is  " << lpStr2<< endl;

    // Path 3 null string as a path.
    int ret_3 = PathAddExtension(lpStr4,lpStr3);
    cout << "The return value is " << ret_3<< endl;
    cout << "The modified path on a null string is " << lpStr4<< endl;

}

OUTPUT:
-----------------------
The original path string 1 is  file
The modified path string 1 is  file.txt
The original path string 2 is  file.doc
The modified path string 2 is  file.doc
The return value is 1
The modified path on a null string is .txt
The return value is 1

Nota

O cabeçalho shlwapi.h define PathAddExtension 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, Windows XP [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	shlwapi.h
biblioteca	Shlwapi.lib
de DLL	Shlwapi.dll (versão 4.71 ou posterior)