The multimedia synchronizer doesn't provide separate controls for synchronizing an entire mediastore versus certain folders or files. You use the same function call to synchronize content whether it's a full, recursive synchronization of all the mediastore content or of only a folder, file, or playlist.
The sync_start command for the mmsyncclient utility and the mm_sync_start() API function both take an argument for specifying the synchronization path. When the path lists a specific file or folder instead of the root folder (/), we refer to that synchronization as a directed synchronization.
The following table shows the path argument syntax and the additional options needed to perform synchronizations of varying scope:
| Scope | Path syntax | Additional options |
|---|---|---|
| Entire mediastore | "/" | MMSYNC_OPTION_RECURSIVE (required) |
| Existing folder | "/$folderpath/" (you can find a folder's path by looking up its folderid in the folders table, and then reading the basepath field from the result row) | MMSYNC_OPTION_RECURSIVE (optional; use to synchronize contents of all subfolders) |
| Existing file | "/$filepath" (you can find an existing file's path by looking up its fid in the files table, reading the result row's folderid field, and then looking up the folder's path, as when synchronizing a folder) | MMSYNC_OPTION_PASS_FILES (required), MMSYNC_OPTION_PASS_METADATA (required) |
| New files (including playlists and subfolders) | "/$folderpath/" (you can find the path of the folder containing the new media files, playlists, and possibly subfolders by looking up the folder's folderid value, as when synchronizing a folder) | MMSYNC_OPTION_PASS_FILES (required), MMSYNC_OPTION_PASS_METADATA (required), MMSYNC_OPTION_RECURSIVE (optional; use to synchronize contents of all subfolders) |
| Entries for an existing playlist | "/$playlistpath" (you can find a playlist's path by joining the playlists and folders tables on the folderid field, then reading the basepath field from the join result) | MMSYNC_OPTION_PASS_PLAYLISTS (required) |
Directed synchronizations are useful when you need information on certain folders or files but you don't want to do an expensive synchronization of all the mediastore content. By directing the synchronization at the folders and files within a path on the mediastore, you can synchronize some media information to make it available sooner to users. You can then synchronize the rest of the information later, if needed.
When a directed synchronization notices a folder that's in the mm-sync database but is not on the mediastore, the synchronization deletes the folder and its contents from the database. With this behavior, a client application can remove a folder from a mediastore and then use directed synchronization to remove this folder from the database.
Synchronization of individual files is typically done when an application knows that a specific file change has occurred: a file has been deleted, added, moved, or renamed. Running the files and metadata synchronization passes on that file will update its information in the database.
To improve the end user's ability to browse a mediastore, such as an iPod, the mm-sync service offers the MMSYNC_OPTION_CANCEL_CURRENT flag. If mm-sync is performing a synchronization but your client application needs to respond to a user action, such as navigating to another folder in the mediastore file explorer, your application can set this flag when calling mm_sync_start() to cancel the current synchronization and start a new synchronization. The cancellation feature helps reduce resource consumption by allowing you to stop synchronizations that become unnecessary when the application goals change.