Метод IVssComponent::AddPartialFile (vswriter.h)

Статья
08/27/2023

Метод AddPartialFile указывает, что резервное копирование выполняется только для частей заданного файла и их частей.

Только модуль записи может вызывать этот метод и только во время операции резервного копирования.

Синтаксис

HRESULT AddPartialFile(
  [in] LPCWSTR wszPath,
  [in] LPCWSTR wszFilename,
  [in] LPCWSTR wszRanges,
  [in] LPCWSTR wszMetadata
);

Параметры

[in] wszPath

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

Путь может содержать переменные среды (например, %SystemRoot%), но не может содержать подстановочные знаки.

Не требуется, чтобы путь заканчивалась обратной косой чертой (""). Приложения, которые извлекают эти сведения для проверка.

Этот путь должен соответствовать или находиться под путем к набору файлов, который уже находится в компоненте (или одному из его подкомпонентов, если компонент определяет набор компонентов).

[in] wszFilename

Строка расширенных символов со значением NULL, содержащая имя файла, участвующего в частичных операциях с файлами. Имя файла (wszFilename) не может содержать подстановочные знаки (* или ?) и должно соответствовать спецификации файла набора файлов, содержащего исходный путь (wszPath).

[in] wszRanges

Строка расширенных символов со значением NULL, содержащая либо список смещения и длины файла, составляющие частичный диапазон поддержки файлов (разделы файла, для которой фактически создается резервная копия), либо имя файла, содержащего такой список.

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

[in] wszMetadata

Строка расширенных символов со значением NULL, содержащая все дополнительные метаданные, необходимые модулю записи для проверки операции частичного восстановления файла. Сведения в этой строке метаданных будут непрозрачными для инициаторов запроса.

Если дополнительные метаданные не требуются, это значение может иметь значение NULL.

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

Ниже приведены допустимые коды возврата для этого метода.

Значение	Значение
S_OK	Элемент успешно задан.
E_INVALIDARG	Одно из значений параметра является недопустимым.
E_OUTOFMEMORY	Вызывающий объект не имеет памяти или других системных ресурсов.
VSS_E_BAD_STATE	Метод не вызывался модулем записи или, если он был вызван модулем записи, не был вызван во время операции восстановления.

Синтаксис списка диапазонов (wszRanges) — это разделенный запятыми список формы offset1:length1, offset2:length2, где каждое смещение и длина — это 64-битовое целое число, указывающее байтовое смещение и длину в байтах соответственно. Смещение и длина могут быть выражены в виде шестнадцатеричных или десятичных значений.

Если wszRange ссылается на файл, содержащий все смещения и длины (файл диапазонов), wszRange будет содержать только полный путь к файлу.

Файл диапазонов должен быть двоичным файлом следующего формата:

64-разрядное целое число, указывающее количество различных диапазонов файлов, для которых требуется создать резервную копию.
Каждый диапазон, выраженный в виде пары 64-разрядных целых чисел: смещение в файле, для резервного копирования в байтах, и длина данных, начиная с этого смещения для резервного копирования.

В любом случае диапазон указывает на подраздел заданного файла, который должен быть резервирован, независимо от остальной части файла.

Инициаторы запроса могут получить сведения о частичном файле с помощью IVssComponent::GetPartialFile и использовать сведения о смещении и длине, возвращаемые GetPartialFile , для восстановления резервных копий разделов в соответствующем расположении копии файла на диске во время восстановления.

AddPartialFile можно применить к файлу, уже управляемому компонентом (или к одному из его подкомпонентов, если компонент определяет набор компонентов), или добавить новый файл в компонент и указать, что он будет участвовать в частичных операциях с файлами.

При указании того, что файл для участия является новым файлом, этот файл должен существовать в теневом томе, а его путь (wszPath) должен соответствовать или находиться под пути, уже находясь в компоненте (или в одном из его подкомпонентов, если компонент определяет набор компонентов). Однако спецификация файла файла (wszFileSpec) не должна соответствовать спецификации файла в компонентах.

Все новые добавленные файлы не будут поддерживать сопоставления альтернативных расположений.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	vswriter.h (включая Vss.h, VsWriter.h)
Библиотека	VssApi.lib

См. также раздел

IVssBackupComponents::SetRangesFilePath

IVssComponent

IVssComponent::GetPartialFile

IVssComponent::GetPartialFileCount