Função PathCleanupSpec (shlobj_core.h)

[PathCleanupSpec está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele pode estar alterado ou indisponível em versões subsequentes.]

Remove caracteres ilegais de um nome de arquivo ou diretório. Impõe o formato de nome de arquivo 8.3 em unidades que não dão suporte a nomes de arquivo longos.

Sintaxe

int PathCleanupSpec(
  [in, optional] PCWSTR pszDir,
  [in, out]      PWSTR  pszSpec
);

Parâmetros

[in, optional] pszDir

Tipo: PCWSTR

Um ponteiro para um buffer encerrado em nulo que contém o caminho totalmente qualificado do diretório que conterá o arquivo ou diretório nomeado em pszSpec. O caminho não deve exceder MAX_PATH caracteres de comprimento, incluindo o caractere nulo de terminação. Esse caminho não é alterado.

Esse valor pode ser NULL.

[in, out] pszSpec

Tipo: PWSTR

Um ponteiro para um buffer encerrado em nulo que contém o nome do arquivo ou diretório a ser limpo. No caso de um arquivo, inclua a extensão do arquivo. Observe que, como '' é considerado um caractere inválido e será removido, esse buffer não pode conter um caminho com mais de um diretório profundo.

Ao sair, o buffer contém uma cadeia de caracteres terminada em nulo que inclui o nome limpo.

Esse buffer deve ter pelo menos MAX_PATH caracteres de comprimento para evitar a possibilidade de um estouro de buffer.

Retornar valor

Tipo: int

Retorna um ou mais dos valores a seguir.

Código de retorno	Descrição
PCS_REPLACEDCHAR	Substituiu um ou mais caracteres inválidos.
PCS_REMOVEDCHAR	Removeu um ou mais caracteres inválidos.
PCS_TRUNCATED	O caminho retornado é truncado.
PCS_PATHTOOLONG	A função falhou porque o caminho de entrada especificado em pszDir é muito longo para permitir a formação de um nome de arquivo válido do pszSpec. Quando esse sinalizador é retornado, ele é sempre acompanhado pelo sinalizador PCS_FATAL.
PCS_FATAL	O caminho limpo não é um nome de arquivo válido. Esse sinalizador sempre é retornado em conjunto com PCS_PATHTOOLONG.

Comentários

A seguir, são considerados caracteres inválidos em todos os nomes.

\ / : * ? " < > |

Os caracteres de controle também são considerados inválidos. Se não houver suporte para nomes de arquivo longos, os caracteres semi-dois-pontos (;) e vírgula (,) também serão inválidos.

A unidade nomeada em pszDir é verificada para determinar se seu sistema de arquivos dá suporte a nomes de arquivos longos. Se isso não acontecer, o nome em pszSpec será truncado para o formato 8.3 e o valor PCS_TRUNCATED retornado. Se pszDir for NULL, a unidade na qual o Windows está instalado será usada para determinar o suporte ao nome de arquivo longo.

Se o caminho completo — o número de caracteres no caminho em pszDir mais o número de caracteres no nome limpo em pszSpec — exceder MAX_PATH – 1 (para considerar o caractere nulo de terminação), a função retornará PCS_PATHTOOLONG.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlobj_core.h (inclua Shlobj.h)
Biblioteca	Shell32.lib
DLL	Shell32.dll (versão 5.0 ou posterior)