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.
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. You can direct the synchronization at folders and files within a path on the mediastore to synchronize part of a mediastore to start playing its contents, and then synchronize other parts of the mediastore in the background or even at a later time.
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 through a mediastore, such as an iPod, the mm-sync service offers the MMSYNC_OPTION_CANCEL_CURRENT flag. If mm-sync is performing a synchronization and your client application needs to start a new synchronization directed at another folder because, for example, the user has navigated to that folder in the mediastore file explorer, your application can set this flag when calling mm_sync_start() to cancel the current synchronization and queue the new synchronization request. The cancellation feature improves application responsiveness because the information for the new files being examined is made available more quickly.