Função PathRelativePathToA (shlwapi.h)

Artigo
11/20/2024

Cria um caminho relativo de um arquivo ou pasta para outro.

Sintaxe

BOOL PathRelativePathToA(
  [out] LPSTR  pszPath,
  [in]  LPCSTR pszFrom,
  [in]  DWORD  dwAttrFrom,
  [in]  LPCSTR pszTo,
  [in]  DWORD  dwAttrTo
);

Parâmetros

[out] pszPath

Tipo: LPTSTR

Um ponteiro para uma cadeia de caracteres que recebe o caminho relativo. Esse buffer deve ter pelo menos MAX_PATH caracteres de tamanho.

[in] pszFrom

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo MAX_PATH que contém o caminho que define o início do caminho relativo.

[in] dwAttrFrom

Tipo: DWORD

Os atributos de arquivo de pszFrom. Se esse valor contiver FILE_ATTRIBUTE_DIRECTORY, pszFrom será considerado um diretório; caso contrário, pszFrom é considerado um arquivo.

[in] pszTo

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo MAX_PATH que contém o caminho que define o ponto de extremidade do caminho relativo.

[in] dwAttrTo

Tipo: DWORD

Os atributos de arquivo de pszTo. Se esse valor contiver FILE_ATTRIBUTE_DIRECTORY, pszTo será considerado diretório; caso contrário, pszTo é considerado um arquivo.

Valor de retorno

Tipo: BOOL

Retorna TRUE se tiver êxito ou false caso contrário.

Observações

Essa função usa um par de caminhos e gera um caminho relativo de um para o outro. Os caminhos não precisam ser totalmente qualificados, mas devem ter um prefixo comum ou a função falhará e retornará FALSE.

Por exemplo, permita que o ponto de partida, pszFrom, seja "c:\FolderA\FolderB\FolderC" e o ponto final, pszTo, seja "c:\FolderA\FolderD\FolderE". PathRelativePathTo retornará o caminho relativo de pszFrom para pszTo como: "....\FolderD\FolderE". Você obterá o mesmo resultado se definir pszFrom como "\FolderA\FolderB\FolderC" e pszTo como "\FolderA\FolderD\FolderE". Por outro lado, "c:\FolderA\FolderB" e "a:\FolderA\FolderD não compartilham um prefixo comum e a função falhará. Observe que "\" não é considerado um prefixo e é ignorado. Se você definir pszFrom como "\FolderA\FolderB" e pszTo como "\FolderC\FolderD", a função falhará.

Exemplos

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

void main(void)
{
    char szOut[MAX_PATH] = "";
    char szFrom[ ] = "c:\\a\\b\\path";
    char szTo[ ] = "c:\\a\\x\\y\\file";

    cout  <<  "The relative path is relative from: ";
    cout  <<  szFrom;
    cout  <<  "\n";

    cout  <<  "The relative path is relative to: ";
    cout  <<  szTo;
    cout  <<  "\n";

    PathRelativePathTo(szOut,
                       szFrom,
                       FILE_ATTRIBUTE_DIRECTORY,
                       szTo,
                       FILE_ATTRIBUTE_NORMAL);

    cout  <<  "The relative path is: ";
    cout  <<  szOut;
    cout  <<  "\n";
}

OUTPUT:
==================
The relative path is relative from: c:\a\b\path
The relative path is relative to: c:\a\x\y\file
The relative path is: ..\..\x\y\file

Nota

O cabeçalho shlwapi.h define PathRelativePathTo 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)

Compartilhar via