Função PathCchCombineEx (pathcch.h)

  • Artigo

Combina dois fragmentos de caminho em um único caminho. Essa função também canoniza todos os elementos de caminho relativo, removendo elementos "." e "." para simplificar o caminho final.

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

Essa função difere de PathAllocCombine porque o chamador deve declarar o tamanho da cadeia de caracteres retornada, que é armazenada na pilha.

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

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

Sintaxe

WINPATHCCHAPI HRESULT PathCchCombineEx(
  [out]          PWSTR  pszPathOut,
  [in]           size_t cchPathOut,
  [in, optional] PCWSTR pszPathIn,
  [in, optional] PCWSTR pszMore,
  [in]           ULONG  dwFlags
);

Parâmetros

[out] pszPathOut

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe a cadeia de caracteres de caminho combinada. Esse parâmetro pode apontar para o mesmo buffer que pszPathIn ou pszMore.

[in] cchPathOut

O tamanho do buffer apontado por pszPathOut, em caracteres.

[in, optional] pszPathIn

Um ponteiro para a primeira cadeia de caracteres de caminho. Esse valor pode ser NULL.

[in, optional] pszMore

Um ponteiro para a segunda cadeia de caracteres de caminho. Se esse caminho começar com uma única barra invertida, ele será combinado apenas com a raiz do caminho apontado por pszPathIn. Se esse caminho for totalmente qualificado, ele será copiado diretamente para o buffer de saída sem ser combinado com o outro caminho. Esse valor pode ser NULL.

[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 construção de caminhos \\?\ mais longos do que MAX_PATH. Observe que cchPathOut deve ser maior que MAX_PATH. Se não for, esse sinalizador será ignorado.
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

Essa função retorna um código HRESULT , incluindo o seguinte.

Código de retorno Descrição
S_OK
 A função foi bem-sucedida. Observe que isso também inclui o caso de uma extensão vazia, como um período sem caracteres a seguir. Nesse caso, a cadeia de caracteres original é retornada sem alterações.
E_INVALIDARG
 Esse valor pode ser causado por várias coisas, como o parâmetro pszPathOut que está sendo definido como NULL ou o valor cchPathOut que está sendo definido como 0 ou um valor maior que PATHCCH_MAX_CCH .
E_OUTOFMEMORY
 A função não pôde alocar memória suficiente para executar a operação.
PATHCCH_E_FILENAME_TOO_LONG
 O tamanho de um ou ambos os caminhos originais excedeu PATHCCH_MAX_CCH .

Comentários

Se pszPathIn e pszMore forem NULL ou apontarem para cadeias de caracteres vazias, uma única barra invertida será copiada para o buffer apontado por pszPathOut.

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

PathCchCanonicalize

PathCchCanonicalizeEx

PathCchCombine