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

Статья
11/20/2024

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

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

Синтаксис

BOOL PathCanonicalizeA(
  [out] LPSTR  pszBuf,
  [in]  LPCSTR 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 Профессиональный, Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shlwapi.h
библиотеки	Shlwapi.lib
DLL	Shlwapi.dll (версия 4.71 или более поздняя)

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