Функция PathCanonicalizeW (shlwapi.h)

Статья
03/02/2024

Упрощает путь, удаляя такие элементы навигации, как "." и ".", чтобы создать прямой, правильно сформированный путь.

Примечание Неправильное использование этой функции может привести к переполнению буфера. Вместо нее рекомендуется использовать более безопасную функцию PathCchCanonicalize или PathCchCanonicalizeEx .

Синтаксис

BOOL PathCanonicalizeW(
  [out] LPWSTR  pszBuf,
  [in]  LPCWSTR pszPath
);

Параметры

[out] pszBuf

Тип: LPTSTR

Указатель на строку, которая получает канонический путь. Необходимо задать размер этого буфера MAX_PATH, чтобы он был достаточно велик для хранения возвращаемой строки.

[in] pszPath

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, с максимальной длиной MAX_PATH, которая содержит канонизируемый путь.

Возвращаемое значение

Тип: BOOL

Возвращает значение TRUE , если результат был вычислен и содержимое выходного буфера lpszDst является допустимым . В противном случае возвращает значение FALSE , а содержимое буфера, на который указывает lpszDst , является недопустимым. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Эта функция позволяет пользователю указать, что следует удалить из пути, вставляя в путь специальные последовательности символов. Последовательность ".." указывает на удаление сегмента пути из текущей позиции в предыдущий сегмент пути. Последовательность ". " указывает, что нужно пропустить следующий сегмент пути к следующему сегменту пути. Корневой сегмент пути не может быть удален.

Если последовательностей ".." больше, чем сегментов пути, функция возвращает значение TRUE , а содержимое буфера, на который указывает lpszDst , содержит только корень "".

Примеры


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

using namespace std;

int main( void )
{
// Path_1 destination buffer.
char buffer_1[MAX_PATH] = "JustABufferToHoldTheCanonicalizedPathForAnExample";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to be Canonicalized.
char buffer_2[ ] = "A:\\name_1\\.\\name_2\\..\\name_3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to be Canonicalized.
char buffer_3[ ] = "A:\\name_1\\..\\name_2\\.\\name_3";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to be Canonicalized.
char buffer_4[ ] = "A:\\name_1\\name_2\\.\\name_3\\..\\name_4";
char *lpStr4;
lpStr4 = buffer_4;

// Path_5 to be Canonicalized.
char buffer_5[ ] = "A:\\name_1\\.\\name_2\\.\\name_3\\..\\name_4\\..";
char *lpStr5;
lpStr5 = buffer_5;

// Path_6 to be Canonicalized.
char buffer_6[ ] = "C:\\..";
char *lpStr6;
lpStr6 = buffer_6;

cout << "The un-canonicalized path 2 is : " << lpStr2
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr2)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 3 is : " << lpStr3
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr3)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 4 is : " << lpStr4
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr4)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 5 is : " << lpStr5
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr5) 
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 6 is : " << lpStr6
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr6)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;
}
OUTPUT:
---------
The un-canonicalized path 2 is : A:\name_1\.\name_2\..\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_3

The un-canonicalized path 3 is : A:\name_1\..\name_2\.\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_2\name_3

The un-canonicalized path 4 is : A:\name_1\name_2\.\name_3\..\name_4
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2\name_4

The un-canonicalized path 5 is : A:\name_1\.\name_2\.\name_3\..\name_4\..
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2

The un-canonicalized path 6 is : C:\..
The return value is            : 1
The canonicalized path 1 is    : C:\

Примечание

Заголовок shlwapi.h определяет PathCanonicalize в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional, Windows XP [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shlwapi.h
Библиотека	Shlwapi.lib
DLL	Shlwapi.dll (версия 4.71 или более поздняя)

Поделиться через