Backup Core Reference

Framework
CoreServices/CoreServices.h
Declared in
BackupCore.h

Overview

Backup Core is a C language API that supplies a low-level interface to file and folder settings used by Backup. Introduced in OS X v10.5, Backup is a built-in, user-configurable backup solution that protects user data from accidental loss.

The Backup Core API includes a function you can use to exclude from Backup temporary or otherwise unimportant folders and files your application creates. In addition, you can use this function to allow your users to make backup decisions from within the context of your application.

Functions

CSBackupIsItemExcluded

Returns a Boolean value indicating whether an item is currently excluded from the backup.

Boolean CSBackupIsItemExcluded (
   CFURLRef item,
   Boolean * excludeByPath
);
Parameters
item

The URL of the item.

excludeByPath

If true, the item’s backup exclusion status applies to its location; if false, the item's backup exclusion status applies to itself, regardless of its location. See CSBackupSetItemExcluded for more information. Can be NULL.

Return Value

true if the item or any of its ancestors are currently excluded from backup, false otherwise.

Availability
  • Available in OS X v10.5 and later.
Declared In
BackupCore.h

CSBackupSetItemExcluded

Includes or excludes an item from the backup.

OSStatus CSBackupSetItemExcluded (
   CFURLRef item,
   Boolean exclude,
   Boolean excludeByPath
);
Parameters
item

The URL of the file or folder to be included or excluded from the backup.

exclude

Pass true to exclude this item from backup (Backup will not back up this item). Pass false to stop excluding this item (Backup will back up this item if the user so chooses).

excludeByPath

Pass true to indicate that this item is excluded because of its location (its absolute path). Pass false to indicate that this item is excluded regardless of its location (and regardless of whether the user moves the item).

Return Value

A result code. Returns noErr if the item was successfully included or excluded from the backup.

Discussion

Backup skips files and folders marked for exclusion. If a folder is marked for exclusion, the folder and all its contents are excluded from the backup process. You can exclude specific paths that do not exist yet, but that you plan to create later, by passing the planned URL in item and passing true in excludeByPath. Note that if you pass false in excludeByPath, the URL must already exist.

Your application can allow users to change the backup exclusion status of any file or folder to which it has write access. To change the backup exclusion status of a path, your application must be running with administrator privileges.

Availability
  • Available in OS X v10.5 and later.
Declared In
BackupCore.h