mm_sync_start()

Start a synchronization

Synopsis:

#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)

Arguments:

hdl
The mm-sync connection handle pointer.
db
The device path of the database to store the synchronized content.
mountpoint
The mountpoint of the mediastore to synchronize.
syncpath
The relative path on the mediastore of the files or folders to synchronize.
options
A bitfield of flags specifying the synchronization options. The following options are supported:
  • MMSYNC_OPTION_PASS_FILES: Perform the files pass.
  • MMSYNC_OPTION_PASS_METADATA: Perform the metadata pass.
  • MMSYNC_OPTION_PASS_PLAYLISTS: Perform the playlist pass.
  • MMSYNC_OPTION_PASS_ALL: Perform all three passes.
  • MMSYNC_OPTION_PASS_CANCEL_CURRENT: Cancel any synchronization in progress on the device before starting the new synchronization.
  • MMSYNC_OPTION_PASS_RECURSIVE: After synchronizing the root folder in the specified path, synchronize its subfolders.
extended_options

A dictionary containing extra options defined as key-value pairs; for details about using dictionaries, see the Dictionary Object API reference.

The supported extended options (i.e., valid keys) include:
  • use_synchronizer: Suggest a preferred synchronizer.
  • force_synchronizer: Force mm-sync to use a particular synchronizer.
  • dynamic_folder: When enabled, keep the file IDs (fids) and playlist IDs (plids) in a folder constant.
  • metadata_keys: Name specific metadata fields to retrieve, as key-value pairs.
  • medialib_uid: Synchronize a specific Media Library when using the mss-ipodiap2.so synchronizer with Apple devices that use iAP2.
  • sync_file_types: Synchronize only files of the specified media types. The types can be one or more of audio, video, photo, or device. Multiple types must be separated by semi-colons (;).

You can set this parameter to NULL if you don't need to use any extended options.

Library:

mmsyncclient

Description:

Start synchronizing the media content contained in syncpath. This path is relative within the filesystem of the mediastore located at mountpoint. The media content gets synchronized to the database that has the device path listed in db. Because mm-sync synchronizes content in a dedicated thread, this function returns before the synchronization starts.

All path-based arguments must refer to valid locations in a locally accessible filesystem.

The syncpath argument is flexible, allowing you to specify these scopes:
  • the entire mediastore
  • a section of the mediastore filesystem, based on a root folder
  • an individual file, which may be a media track or a playlist

When the synchronization path refers to a folder, you must terminate it with a slash (/). To look in subfolders, set the MMSYNC_OPTION_RECURSIVE flag in options. When the path is an individual 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 mediastores don't support synchronizations of specific folders or files. For these mediastores, you must synchronize all content by specifying a path of “/”.

The extended_options field configures extra settings, and supports these keys and values:
Key Value Description
use_synchronizer “mss_name” (a supported synchronizer, as a string in quotes; e.g., "dvdaudio") Use the specified synchronizer if it supports the current operation; otherwise, do nothing.
force_synchronizer “mss_name” (a supported synchronizer, as a string in quotes; e.g., "dvdvideo") Force the use of the specified synchronizer, whether or not it supports the current operation.
dynamic_folder enable or disable

Enable or disable the dynamic setting for the folder listed in syncpath. By default, this setting is disabled.

When this setting is enabled, the file IDs (fids) and playlist IDs (plids) for items in this folder remain constant. The setting is nonrecursive, so only the files in the top-level folder given in syncpath are affected; files in subfolders aren't.

For details on how this setting impacts synchronization, see “Maintaining constant IDs for updated files and playlists”.
metadata_keys

The metadata fields to be read, as name-value pairs separated by semi-colons:

md_title_name=Diablo;
md_title_genre=Horror;
md_title_album=DemonSeed;
md_title_artist=Mr_X

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

When you define metadata_keys, the libmd library is not 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.
medialib_uid

The UID of the Media Library to synchronize. This setting applies only if you're using the mss-ipodiap2.so synchronizer to upload metadata from Apple devices that use iAP2.

The value is a long alphanumeric string with individual sections followed by a version number:

38D4C73C-AACA-4015-B5E8-
5EC83AC9B521-4954524C-
9.2.1

To learn the UID of a Media Library, you can call a certain function in the iPod Accessory Protocol version 2 (iAP2) API and read the UID from a data structure written by this function. The iAP2 interface is fully explained in the Working with Apple Devices reference available through the Apple documentation package in QNX Software Center.

You can also read the UID from the PPS object located at /pps/services/multimedia/iap2/medialibrary, which contains the same information provided by the iAP2 API.

If you don't specify the medialib_uid option, mm-sync synchronizes the metadata from the first Media Library, which contains all of the device's media content.
sync_file_types One or more media types. Individual values must be separated by semi-colons (;). Values can be any of: audio, video, photo, or device

The media types to be synchronized. Any file that's in the synchronization path and whose type matches one of the listed types will have its metadata synchronized.

For example, suppose you synchronize a mediastore folder containing .mp4 files, some of which are audio and some of which are video. If you set sync_file_types to audio, only the audio files (i.e., those that don't have a video component) have their metadata synchronized.

Returns:

On success, a value greater than 0 that refers to the synchronization operation ID. On failure, -1 is returned.