Start a synchronization.


#include <mmsync/mmsyncclient.h>
int mm_sync_start( mmsync_hdl_t *hdl, 
                   const char *db, 
                   const char *mountpoint, 
                   const char *syncpath, 
                   uint32_t options, 
                   const strm_dict_t *extended_options )



The mm-sync connection handle


The device path of the database where the content is to be synchronized


The mountpoint of the mediastore to synchronize


The relative path on the mediastore for the files or folders to synchronize


The following synchronization options apply:

Perform the files pass.
Perform the metadata pass.
Perform the playlists pass.
Perform all three passes.
Cancel any synchronization in progress on the device before starting the new synchronization.
After synchronizing the root folder in the specified path, synchronize its subfolders and their contents.

You can enable any combination of synchronization options by separating multiple flags with the bitwise OR operator (|). For example, to do the first two passes recursively, set options to: MMSYNC_OPTION_PASS_FILES | MMSYNC_OPTION_PASS_METADATA | MMSYNC_OPTION_PASS_RECURSIVE

A set of key/value pairs with extended synchronization options, formatted as a comma-separated list of pairs:
This parameter may be NULL.
Key Value Description
use_synchronizer mss name (a text string naming a supported synchronizer; for example, dvdaudio) Use the specified synchronizer if it supports the current operation; otherwise, do nothing.
force_synchronizer mss name (a text string naming a supported synchronizer; for example, dvdvideo) Force the use of the specified synchronizer, whether or not it supports the current operation.
dynamic_folder enable | disable

Enable or disable the dynamic setting for the folder specified in syncpath. The fids for files in this folder will remain constant while this setting is enabled. The setting is nonrecursive, so the only files affected are those in the top-level folder given in syncpath; files in subfolders aren't affected.

For information on how this setting impacts synchronization, see "Maintaining constant IDs for updated files and playlists".


The names of metadata fields to be read, with individual fields separated by semi-colons (;):


Retrieve only the listed metadata fields. This setting is effective only for directed synchronizations in which dynamic_folder is enabled.

When you define metadata_keys, the libmd library isn't used for metadata extraction; instead, mm-sync sets the metadata fields to the values listed in this option.

You must provide values for each field that you list.




Start a synchronization of the media content in the specified synchronization path. This path is relative within the filesystem of the mediastore located at the specified mountpoint. The media content is synchronized to the database identified by the device path. The mm-sync process performs the synchronization in a dedicated thread, so this call returns before the synchronization begins.

All path arguments must contain valid locations in a locally accessible filesystem. The syncpath argument is highly flexible, allowing you to set the following synchronization scopes:

For synchronizations of content from multiple folders on the mediastore, you must set the MMSYNC_OPTION_RECURSIVE flag to instruct mm-sync to look in the subfolders under the top-level folder named in the path. When the path is a folder, you must terminate the path string with a slash ("/"). Specifying a path of "/" synchronizes the entire mediastore. When the path is a file, you must set both the MMSYNC_OPTION_PASS_FILES and MMSYNC_OPTION_PASS_METADATA flags for media files and set the MMSYNC_OPTION_PASS_PLAYLISTS flag for playlists.

Some mediastore types don't support synchronizations directed at folders or files. For these mediastores, you must synchronize all the content on the device.


>0 values refer to the synchronization operation ID on success; -1 is returned on failure