Função PathCchAppendEx (pathcch.h)

  • Artigo

Acrescenta um caminho ao final de outro.

Essa função difere de PathCchAppend , pois permite que um caminho final mais longo seja construído.

Essa função difere de PathAppend , pois aceita caminhos com prefixos "\", "\?" e "\?\UNC".

Nota Essa função, ou PathCchAppend, deve ser usada no lugar de PathAppend para evitar a possibilidade de um estouro de buffer.

Sintaxe

WINPATHCCHAPI HRESULT PathCchAppendEx(
  [in, out]      PWSTR  pszPath,
  [in]           size_t cchPath,
  [in, optional] PCWSTR pszMore,
  [in]           ULONG  dwFlags
);

Parâmetros

[in, out] pszPath

Um ponteiro para um buffer que, na entrada, contém o caminho original. Quando essa função retorna com êxito, o buffer contém o caminho original mais o caminho acrescentado.

[in] cchPath

O tamanho do buffer apontado por pszPath, em caracteres.

[in, optional] pszMore

Um ponteiro para o caminho a ser acrescentado ao final do caminho apontado por pszPath. Os caminhos e caminhos UNC que começam com a sequência \?\ são aceitos e reconhecidos como caminhos totalmente qualificados. Esses caminhos substituem a cadeia de caracteres apontada por pszPath em vez de serem acrescentados a ela.

[in] dwFlags

Um ou mais dos seguintes sinalizadores:

Valor Significado
PATHCCH_NONE
0x0000000
 Não permita a construção de caminhos \\?\ (ou seja, caminhos longos) mais longos do que MAX_PATH.
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 Permitir a criação de caminhos \\?\ por mais tempo do que MAX_PATH.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 Força a API a tratar o chamador como caminho longo habilitado, independentemente do estado habilitado para nome longo do processo. Essa opção só pode ser usada quando PATHCCH_ALLOW_LONG_PATHS é especificado e não pode ser usada com PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 Força a API a tratar o chamador como caminho longo desabilitado, independentemente do estado habilitado para nome longo do processo. Essa opção só pode ser usada quando PATHCCH_ALLOW_LONG_PATHS é especificado e não pode ser usada com PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 Desabilita a normalização de segmentos de caminho que inclui a remoção de pontos e espaços à direita. Isso permite o acesso a caminhos que a normalização do caminho win32 bloqueará.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 Converte o caminho de entrada no formulário de caminho do dispositivo DOS de comprimento estendido (com o prefixo \\?\ se ainda não estiver nesse formulário. Isso permite o acesso a caminhos que, de outra forma, não podem ser endereçáveis devido a regras de normalização do Win32 (que podem remover pontos e espaços à direita) e limitações de comprimento do caminho. Essa opção implica o mesmo comportamento de PATHCCH_DO_NOT_NORMALIZE_SEGMENTS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código HRESULT , incluindo o seguinte.

Código de retorno Descrição
E_INVALIDARG
 PszPath ou pszMore é NULL, cchPath é 0 ou cchPath é maior que PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 A cadeia de caracteres resultante excederia PATHCCH_MAX_CCH.
E_OUTOFMEMORY
 A função não pôde alocar um buffer do tamanho necessário.

Comentários

Essa função insere uma barra invertida entre as duas cadeias de caracteres, se uma ainda não estiver presente.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho pathcch.h
Biblioteca Pathcch.lib

Confira também

PathCchAppend