IVssComponent::AddDifferencedFilesByLastModifyTime method (vswriter.h)
The AddDifferencedFilesByLastModifyTime method is used by a writer to indicate that a file set (a specified file or files) should be evaluated against a last modification time stamp for inclusion in a time stamped incremental or differential backup using entire files, not partial files.
This method can be called by a writer only during a backup operation.
Syntax
HRESULT AddDifferencedFilesByLastModifyTime(
[in] LPCWSTR wszPath,
[in] LPCWSTR wszFilespec,
[in] BOOL bRecursive,
[in] FILETIME ftLastModifyTime
);
Parameters
[in] wszPath
Null-terminated wide character string containing the name of the directory or directory hierarchy containing the files to be mapped.
The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
[in] wszFilespec
Null-terminated wide character string containing the file specification of the files to be mapped.
A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
[in] bRecursive
A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is treated as a hierarchy of directories to be traversed recursively, or false if not.
For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points.
[in] ftLastModifyTime
The writer specification of the time of last modification for the difference files, expressed as a FILETIME structure.
The last-modify time is always given in Greenwich Mean Time.
Return value
The following are the valid return codes for this method.
| Value | Meaning |
|---|---|
|
Successfully added differenced files. |
|
One of the parameter values is not valid. |
|
The caller is out of memory or other system resources. |
|
This method was not called by a writer or, if called by a writer, it either was not called during a backup operation or was called while handling a BackupComplete or BackupShutdown event. |
|
The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS. |
|
Unexpected error. The error code is logged in the error log file. For more information, see
Event and Error Handling Under VSS.
Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 and Windows 7. E_UNEXPECTED is used instead. |
Remarks
A writer calls this method to specify that certain files in a component should be backed up only if they have been modified since a certain time. For more information, see Backup By Last Modify Time.
This method can be called only by writers supporting the last modified schema (VSS_BS_LAST_MODIFY), and only during backup operations. Writers using this method do not have to support the time-stamp schema (VSS_BS_TIMESTAMPED).
Files added by AddDifferencedFilesByLastModifyTime should not also be added by IVssComponent::AddPartialFile.
If the backup type (VSS_BACKUP_TYPE) is incremental (VSS_BT_INCREMENTAL), writers using AddDifferencedFilesByLastModifyTime must support the incremental schema (VSS_BS_INCREMENTAL). If the backup type is differential, the writer must support the VSS_BS_DIFFERENTIAL schema.
The AddDifferencedFilesByLastModifyTime method should be called prior to the actual start of a backup operation, typically while handling the PostSnapshot event (see CVssWriter::OnPostSnapshot).
If the time-stamp value set by AddDifferencedFilesByLastModifyTime is nonzero, a requester must respect this value regardless of its own records and file system information when determining if the differenced file should be included in a differential or incremental backup.
If the time stamp set by AddDifferencedFilesByLastModifyTime (ftLastModifyTime) is zero, the requester can use file system information and its own records to determine whether the differenced files should be included in a differential or incremental backup.
Requesters retrieve the number of differenced files managed by a component by calling IVssComponent::GetDifferencedFile.
Differenced file sets can be either of the following:
- A member of the current component or (if the component defines a component set) its subcomponents
- New files not previously included in the component or subcomponents. The AddDifferencedFilesByLastModifyTime method allows writers to indicate that files created since the original backup should be included in the component to support incremental or differential backups.
When adding new files to the component, AddDifferencedFilesByLastModifyTime, the writer should not add files managed by another component or writer.
There is no method in the IVssComponent interface that allows for changing or adding an alternate location mappings for new files added by AddDifferencedFilesByLastModifyTime. If an alternate location mapping corresponds to the new file, then that alternate location will be used.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | vswriter.h (include Vss.h, VsWriter.h) |
| Library | VssApi.lib |
See also
IVssComponent::GetDifferencedFile
IVssComponent::GetDifferencedFilesCount