mme_sync_directed()

Start a directed synchronization

Synopsis:

#include <mme/mme.h>

int mme_sync_directed( mme_hdl_t *hdl,
                       uint64_t msid,
                       const char *path,
                       uint32_t options );


Arguments:

hdl
An MME connection handle.
msid
The ID for the mediastore on which directed synchronization is to be performed.
path
The path to be synchronized on the mediastore.
options
The synchronization options. The options can be any combination of:

Library:

mme

Description:

The function mme_sync_directed() starts directed synchronization for a specified path on a mediastore.

Directed synchronization allows you to synchronize only a specified path on a mediastore. This capability is particularly useful if you want to synchronize part of a large mediastore in order to start playing its contents, then synchronize the rest (or other parts) of the mediastore in the background or at a later time.


Note: Directed synchronization is only available for mediastores with hierarchical directory structures: HHDs, iPods, USB sticks, data CDs, etc. It is not available for mediastores, such as music CDs, that have a single-level directory structure.


Caution: A clean up of invalid copied_id fields can take a long time. Use the MME_SYNC_OPTION_CLR_INV_COPIED flag judiciously — only when synchronizing after deleting media files from your database.

Events

This function returns synchronization events with the operation ID. See the chapter MME Synchronization Events for a full list.

Blocking and validation

This function is non-blocking. It returns asynchronously. On completion, it returns a positive integer, which is the operation ID. This return value is sent with the event:

Returns:

>0
Success: the operation ID of the directed synchronization.
-1
An error occurred (errno is set).

Examples:

The code snippet below shows an example of how directed synchronization can be used:

uint64_t go_to_folder (
    mme_hdl_t *mme,
    qdb_hdl_t *db,
    uint64_t msid,
    uint64_t folderid,
    const char *folder_name
)
{
    int rc;

    /* if it's already synced, don't resync it unless forced */
    if ( force_resync || ( ! folder_synced( db, msid, folderid ) ) ) {
        rc = mme_sync_directed( mme, msid, folder_name, MME_SYNC_OPTION_PASS_ALL );
        if ( rc == -1 ) {
            fprintf( stderr, "Unable to get sync path \"%s\": %s (%d).\n",
                     folder_name, strerror( errno ), errno );
            return 0;
        }

        if ( waitfor_directed_syncevent( rc ) != 1 ) {
            /* operation didn't finish, or failed */
            fprintf( stderr, "**** Operation failed. ****\n" );
            return 0;
        }
    }
    return folderid;
}

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

mme_directed_sync_cancel(), mme_playlist_sync(), mme_resync_mediastore(), mme_setpriorityfolder(), mme_sync_cancel(), mme_sync_file(), mme_sync_get_msid_status(), mme_sync_get_status()