mmsync_event_type_t

mm-sync event types

Synopsis:

#include <mmsync/event.h>
typedef enum mmsync_event_type {
    MMSYNC_EVENT_NONE = 0,
    MMSYNC_EVENT_MS_1PASSCOMPLETE,
    MMSYNC_EVENT_MS_SYNCCOMPLETE,
    MMSYNC_EVENT_MS_UPDATE,
    MMSYNC_EVENT_SHUTDOWN,
    MMSYNC_EVENT_SHUTDOWN_COMPLETED,
    MMSYNC_EVENT_MS_SYNCFIRSTFID,
    MMSYNC_EVENT_SYNC_ERROR,
    MMSYNC_EVENT_SYNCABORTED,
    MMSYNC_EVENT_SYNC_SKIPPED,
    MMSYNC_EVENT_MS_SYNC_STARTED,
    MMSYNC_EVENT_MS_2PASSCOMPLETE,
    MMSYNC_EVENT_MS_3PASSCOMPLETE,
    MMSYNC_EVENT_MS_SYNC_PENDING,
    MMSYNC_EVENT_MS_SYNC_FOLDER_STARTED,
    MMSYNC_EVENT_MS_SYNC_FOLDER_COMPLETE,
    MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_STARTED,
    MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_COMPLETE,
    MMSYNC_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE,
    MMSYNC_EVENT_MS_SYNC_FIRST_EXISTING_FID,
    MMSYNC_EVENT_BUFFER_TOO_SMALL,
    MMSYNC_EVENT_MS_SYNC_FOLDER_TRIM_COMPLETE,
    MMSYNC_EVENT_DB_RESET,
    MMSYNC_EVENT_PLAYLIST_ENTRIES_UPDATE
} mmsync_event_type_t;

Data:

MMSYNC_EVENT_NONE

Name: MMSYNC_EVENT_NONE

Description: Indicates there are no events in the client's queue. This event is returned if the client calls mm_sync_events_get() when no events have occurred.

Delivered when: Never delivered.

Event data: None.

DB tables updated: None (event is not related to database updates).

Class: Not defined

MMSYNC_EVENT_MS_1PASSCOMPLETE

Name: MMSYNC_EVENT_MS_1PASSCOMPLETE

Description: The files pass of synchronization is complete.

The files pass updates the files, folders, and playlists tables with all files (tracks and playlists) found on the device. Items that used to exist but are no longer on the device are removed. The mediastore_metadata table is also updated with the synchronizer used, the device's mountpoint, and the completion time of the files pass (in the last_sync and syncflags fields). No metadata has been gathered at this point.

Delivered when: The files pass completes.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • files
  • folders
  • playlists
  • mediastore_metadata

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNCCOMPLETE

Name: MMSYNC_EVENT_MS_SYNCCOMPLETE

Description: The synchronization of the mediastore is complete. All tables are as accurate as possible.

Delivered when: All synchronization passes are complete for the mediastore for which the synchronization was requested.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • files
  • folders
  • playlists
  • playlist_entries
  • audio_metadata (if necessary)
  • video_metadata (if necessary)
  • photo_metadata (if necessary)
  • genres (if necessary)
  • artists (if necessary)
  • albums (if necessary)
  • mediastores

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_UPDATE

Name: MMSYNC_EVENT_MS_UPDATE

Description: Database content related to a mediastore has been updated.

Delivered when: The mm-sync service has written new data to the database. This event tells the client which mediastore the changes are associated with and provides the client with information on the source of the changes.

An event of this type is delivered following each change in the synchronization pass flag settings, for each operation ID associated with a specific mediastore.

Event data: The mmsync_ms_update_data_t structure, which contains:
  • the number of added files and folders
  • the synchronization pass under which any changes were made (flags field)
  • the synchronization operation ID
  • the timestamp field, which is the same value as the mm-sync timestamp assigned to the last_sync field of all files entries adjusted during this update

DB tables updated: Depends on which synchronization pass (if any) changed the database.

Database changed outside of synchronization (i.e., flags == 0):
  • files
Files pass (i.e., flags == MMSYNC_SYNC_OPTION_PASS_FILES):
  • files
  • folders
  • playlists
  • mediastore_metadata
Metadata pass (i.e., flags == MMSYNC_SYNC_OPTION_PASS_METADATA):
  • files
  • folders
  • audio_metadata, video_metadata, photo_metadata, genres, artists, albums (some or all of these tables depending on the categories of the media files)
  • mediastore_metadata
Playlist pass (i.e., flags == MMSYNC_SYNC_OPTION_PASS_PLAYLISTS):
  • files
  • folders
  • playlists
  • playlist_entries
  • mediastore_metadata

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_SHUTDOWN

Name: MMSYNC_EVENT_SHUTDOWN

Description: A client requested the mm-sync service to shut down. This event informs other clients about the shutdown request.

Delivered when: Immediately after receiving the request to shut down but before the shutdown process begins.

Event data: None.

DB tables updated: None (event is not related to database updates).

Class: MMSYNC_EVENT_CLASS_GENERAL

MMSYNC_EVENT_SHUTDOWN_COMPLETED

Name: MMSYNC_EVENT_SHUTDOWN_COMPLETED

Description: The mm-sync service has finished its shutdown process (following a shutdown request) and is no longer active. The service must be terminated and restarted to synchronize mediastores again.

Delivered when: The shutdown process is complete and playback and synchronization have stopped.

Event data: None.

DB tables updated: None (event is not related to database updates).

Class: MMSYNC_EVENT_CLASS_GENERAL

MMSYNC_EVENT_MS_SYNCFIRSTFID

Name: MMSYNC_EVENT_MS_SYNCFIRSTFID

Description: During the files pass, the first new file that's playable by mm-sync was found. This event is delivered so clients can start playback as soon as possible.

Delivered when: The first new playable file has been found and placed in the library, just after the file entries marked for deletion were removed from the database. This event is delivered during full, recursive synchronizations as well as directed synchronizations. When this event is emitted, the receiver knows that all database items are valid.

Event data: The mmsync_first_fid_data_t structure, which contains:
  • the fid of the first file
  • the synchronization operation ID
  • the timestamp field, which is the same value as the mm-sync timestamp assigned to the last_sync field of all file entries modified by this update
DB tables updated:
  • files
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_SYNC_ERROR

Name: MMSYNC_EVENT_SYNC_ERROR

Description: An error occurred during synchronization.

Delivered when: Various synchronization errors will cause this event to be generated; the event data indicates the exact cause.

Event data: The mmsync_sync_error_t structure, which contains:
  • the error type
  • the synchronization operation ID
  • additional information; often, the ID of the folder in which the event occurred

DB tables updated: Depends on the error type.

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_SYNCABORTED

Name: MMSYNC_EVENT_SYNCABORTED

Description: The synchronization on the mediastore was aborted before completing. This happens when the device is removed, the synchronization is cancelled by the user, or there's a serious failure.

Delivered when: The synchronization is stopped on the mediastore before completing successfully.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID

DB tables updated: None (event is not related to database updates).

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_SYNC_SKIPPED

Name: MMSYNC_EVENT_SYNC_SKIPPED

Description: The synchronization wasn't started automatically on a mediastore. The user can still request a manual synchronization.

Delivered when: A mediastore is inserted and a manual synchronization can be requested.

Event data: None.

DB tables updated:
  • mediastores

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_STARTED

Name: MMSYNC_EVENT_MS_SYNC_STARTED

Description: The synchronization has begun on a mediastore.

Delivered when: The synchronization starts on a mediastore.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • mediastores

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_2PASSCOMPLETE

Name: MMSYNC_EVENT_MS_2PASSCOMPLETE

Description: The metadata pass of synchronization is complete.

The metadata pass updates only some metadata tables, based on the type of media files being synchronized. The files table is updated to show that all metadata describing the media content is now accurate. The mediastore_metadata table is updated to reflect the completion time of the metadata pass (in the last_sync and syncflags fields).

Delivered when: The metadata pass completes.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • audio_metadata
  • video_metadata
  • photo_metadata
  • genres
  • artists
  • albums
  • mediastore_metadata

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_3PASSCOMPLETE

Name: MMSYNC_EVENT_MS_3PASSCOMPLETE

Description: The playlist pass of synchronization is complete.

Information on device playlists is now accurate in the database. The mediastore_metadata table is updated to reflect the completion time of the playlist pass (in the last_sync and syncflags fields).

Delivered when: The playlist pass completes.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • files
  • folders
  • playlists
  • playlist_entries
  • mediastore_metadata

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_PENDING

Name: MMSYNC_EVENT_MS_SYNC_PENDING

Description: A synchronization was requested for a mediastore but the operation was put on the pending (waiting) list because no synchronization threads were available.

Delivered when: After the mediastores table is updated but there are no synchronization threads available to continue synchronizing the mediastore.

Event data: The mmsync_sync_data_t structure, which contains:
  • the error type (if applicable)
  • the synchronization operation ID
DB tables updated:
  • mediastores

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_FOLDER_STARTED

Name: MMSYNC_EVENT_MS_SYNC_FOLDER_STARTED

Description: A folder that has started synchronization.

Delivered when: The synchronization of a folder has started. On the files pass, this event is emitted after the folder has been inserted into the database. On the metadata pass, this is emitted just before the folder contents go through the metadata pass.

Event data: The mmsync_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder in which the event occurred
  • the number of files, folders, and playlists synchronized in this pass, which is 0 for all three fields
  • the timestamp field, which is set to 0 and not used
DB tables updated:
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_FOLDER_COMPLETE

Name: MMSYNC_EVENT_MS_SYNC_FOLDER_COMPLETE

Description: All files in a folder have been synchronized and the subfolders in the folder have been enumerated.

Delivered when: The nonrecursive synchronization of a folder has completed.

Event data: The mmsync_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder in which the event occurred

The structure also contains pass-specific information, as follows:

Files pass:
  • the number of file, folder, and playlist entries added to the database
Metadata pass:
  • the number of files for which the metadata was changed. The number of folders and playlists marked as changed is always 0. The timestamp field stores the value of the last_sync column in the folders table.
Playlist pass:
  • the number of playlists synchronized
DB tables updated:
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_STARTED

Name: MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_STARTED

Description: A priority folder has started synchronization.

Delivered when: The synchronization of a priority folder has started.

Event data: The mmsync_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder in which the event occurred
DB tables updated:
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_COMPLETE

Name: MMSYNC_EVENT_MS_SYNC_FOLDER_COMPLETE

Description: A priority folder has completed synchronization.

Delivered when: The synchronization of a priority folder, which must be nonrecursive, has completed.

Event data: The mmsync_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder in which the event occurred
  • the number of files, folders, and playlists within the indicated folder synchronized in this pass
DB tables updated:
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE

Name: MMSYNC_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE

Description: The synchronization of all subfolders in a folder is complete.

Delivered when: The recursive synchronization of a folder has completed. This event isn't emitted for a nonrecursive synchronization of a folder.

Event data: The mmsync_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder in which the event occurred
  • the number of subfolders synchronized in this pass
  • the number of files and the number of playlists synchronized in this pass, which are both set to 0 and not used
  • the timestamp field, which is set to 0 and not used
DB tables updated:
  • folders

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_MS_SYNC_FIRST_EXISTING_FID

Name: MMSYNC_EVENT_MS_SYNC_FIRST_EXISTING_FID

Description: During the files pass, the first existing file that's playable by mm-sync was found. This event is delivered so clients can start playback as soon as possible.

Delivered when: The first playable file that's already in the library was found on the mediastore. This event is delivered during full, recursive synchronizations as well as directed synchronizations.

Event data: The mmsync_first_fid_data_t structure, which contains:
  • the fid of the first file
  • the synchronization operation ID
  • the timestamp field, which indicates the time the files pass was started

DB tables updated: None.

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_BUFFER_TOO_SMALL

Name: MMSYNC_EVENT_BUFFER_TOO_SMALL

Description: The event buffer on the client side is too small to fetch events from mm-sync.

Delivered when: A client requests an event but doesn't have enough room to hold it.

Event data: The mmsync_event_queue_size_t structure, which contains:
  • the size (in bytes) of the first queued event
  • the size (in bytes) of all queued events

DB tables updated: None.

Class: MMSYNC_EVENT_CLASS_GENERAL

MMSYNC_EVENT_MS_SYNC_FOLDER_TRIM_COMPLETE

Name: MMSYNC_EVENT_MS_SYNC_FOLDER_TRIM_COMPLETE

Description: All database entries no longer in a folder have been deleted from the database.

Delivered when: During the files pass, if a folder is found to have been previously synchronized, this event is emitted after all the items determined to have been removed from the folder have been deleted from the database.

After this event, users know that any database items shown as being in the folder are valid.

Event data: The mmsync_folder_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the current synchronization pass, which is always 1 (for the files pass)
  • the ID of the folder in which the event occurred
  • the number of files, subfolders, and playlists deleted from the folder during this pass
  • the timestamp field, is the start time of the synchronization
DB tables updated:
  • files
  • folders
  • playlists
  • playlist_entries

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_DB_RESET

Name: MMSYNC_EVENT_DB_RESET

Description: All file, metadata, and playlist information has been cleared from the database.

Delivered when: During synchronization, when an Apple device instructs mm-sync to delete all database contents.

Event data: The mmsync_reset_sync_data_t structure, which contains:
  • the synchronization operation ID
  • a timestamp value set to the mm-sync timestamp assigned to the last_sync fields of all file entries impacted by the reset operation
DB tables updated:
  • files
  • playlists
  • playlist_data
  • mediastore_metadata
  • audio_metadata
  • video_metadata
  • ipod_metadata
  • genres
  • artists
  • albums

Class: MMSYNC_EVENT_CLASS_SYNC

MMSYNC_EVENT_PLAYLIST_ENTRIES_UPDATE

Name: MMSYNC_EVENT_PLAYLIST_ENTRIES_UPDATE

Description: The number of playlist entries queried for updates has reached the configured limit on how many can be queried before an event notification is sent. If any playlist entries need to be updated in the database, the MMSYNC_EVENT_MS_UPDATE event is also sent.

Delivered when: After the nth query for a playlist entry update has been issued, where n is defined in the mm-sync configuration file.

Event data: The mmsync_pl_entries_sync_data_t structure, which contains:
  • the synchronization operation ID
  • the ID of the playlist being synchronized
  • the OID of the last playlist entry confirmed to be in the database
  • the number of playlist entries already updated
  • the number of playlist entries that will be checked for an update
DB tables updated:
  • playlist_entries

Class: MMSYNC_EVENT_CLASS_SYNC

Library:

mmsyncclient