mmsync_event_type_t

mm-sync event types.

Synopsis:

#include <mmsync/event.h>
typedef enum mmsync_sync_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_sync_event_type_t;

Data:

MMSYNC_EVENT_NONE

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

MMSYNC_EVENT_MS_1PASSCOMPLETE

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 synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

DB tables updated: files, folders, playlists, and mediastore_metadata.

MMSYNC_EVENT_MS_SYNCCOMPLETE

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 synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

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), and mediastores.

MMSYNC_EVENT_MS_UPDATE

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 the changes were made (if any)
  • 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 change outside of a synchronization operation (mmsync_ms_update_event_t.flags == 0): files.

Files pass (mmsync_ms_update_event_t.flags == MMSYNC_SYNC_OPTION_PASS_FILES): files, folders, playlists, and mediastore_metadata.

Metadata pass (mmsync_ms_update_event_t.flags == MMSYNC_SYNC_OPTION_PASS_METADATA): files, folders, audio_metadata (if necessary), video_metadata (if necessary), photo_metadata (if necessary), genres (if necessary), artists (if necessary), albums (if necessary), and mediastore_metadata.

Playlist pass (mmsync_ms_update_event_t.flags == MMSYNC_SYNC_OPTION_PASS_PLAYLISTS): files, folders, playlists, playlist_entries, and mediastore_metadata.

MMSYNC_EVENT_SHUTDOWN

Description: A client can request the mm-sync service to shut down. This event allows other clients to know that mm-sync was requested to shut down.

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

Event data: None.

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

MMSYNC_EVENT_SHUTDOWN_COMPLETED

The mm-sync service was requested to shutdown. This event indicates that mm-sync has finished its shutdown process and is no longer active. The mm-sync service must be terminated and restarted to perform actions again.

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

Event data: None.

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

MMSYNC_EVENT_MS_SYNCFIRSTFID

The first new file that is playable by mm-sync was found during the files pass. This event is delivered so clients can start playback as soon as possible. If there are files to remove from the database, this event is not emitted until all these files have been removed. When this event is emitted, the receiver knows all database items are valid.

Delivered when: The first new playable file has been found and placed in the library, just after the mediastore items marked for deletion were removed from the database.

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 files entries adjusted during this update

DB tables updated: files and folders.

MMSYNC_EVENT_SYNC_ERROR

An error occurred during syncing.

Delivered when: Various synchronization errors will cause this event to be generated; the event data indicates the 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.

MMSYNC_EVENT_SYNCABORTED

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 another serious failure.

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

Event data: The synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

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

MMSYNC_EVENT_SYNC_SKIPPED

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

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

Event data: None.

DB Tables Updated: mediastores.

MMSYNC_EVENT_MS_SYNC_STARTED

The synchronization has begun on a mediastore.

Delivered when: The synchronization starts on a mediastore.

Event data: The synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

DB Tables Updated: mediastores.

MMSYNC_EVENT_MS_2PASSCOMPLETE

The metadata pass of synchronization is complete.

The metadata pass updates only some of the 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 synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

DB tables updated: audio_metadata, video_metadata, photo_metadata, genres, artists, albums, and mediastore_metadata.

MMSYNC_EVENT_MS_3PASSCOMPLETE

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 synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

DB tables updated: files, folders, playlists, playlist_entries, and mediastore_metadata.

MMSYNC_EVENT_MS_SYNC_PENDING

A synchronization has been 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 and there are no synchronization threads available to continue synchronizing the mediastore.

Event data: The synchronization data providing the operation ID and the synchronization error type (when applicable). These fields are stored in the mmsync_sync_data_t structure.

DB tables updated: mediastores.

MMSYNC_EVENT_MS_SYNC_FOLDER_STARTED

A folder has started synchronization.

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

Event data: The mmsync_folder_sync_data_t structure, which contains:

  • the ID of the folder in which the event occurred
  • the current synchronization pass
  • 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
  • the synchronization operation ID

DB tables updated: folders.

MMSYNC_EVENT_MS_SYNC_FOLDER_COMPLETE

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_folder_sync_data_t structure, which stores the synchronization operation ID, the current synchronization pass, the ID of the folder in which the event occurred, and other information specific to the current pass.

During the files pass, the structure contains the number of files, folders, and playlists added to the database.

During the metadata pass, the structure contains the number of files for which the metadata was changed. The number of folders and playlists changed is always 0. The timestamp field is set to the value of the last_sync column in the folders table.

During the playlist pass, the structure contains the number of playlists synchronized.

DB tables updated: folders.

MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_STARTED

A priority folder has started synchronization.

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

Event data: The mmsync_folder_sync_data_t structure, which contains:

  • the synchronization operation ID
  • the current synchronization pass
  • the ID of the folder being synchronized

DB tables updated: folders.

MMSYNC_EVENT_MS_SYNC_PRIORITY_FOLDER_COMPLETE

A priority folder has completed synchronization.

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

Event data: The mmsync_folder_sync_data_t structure, which contains:

  • the ID of the folder in which the event occurred
  • the current synchronization pass
  • the number of files, folders, and playlists within the indicated folder synchronized in this pass
  • the synchronization operation ID

DB tables updated: folders.

MMSYNC_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE

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_folder_sync_data_t structure, which contains:

  • the ID of the folder in which the event occurred
  • the current synchronization pass
  • 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
  • the synchronization operation ID

DB tables updated: folders.

MMSYNC_EVENT_MS_SYNC_FIRST_EXISTING_FID

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

Delivered when: The first existing playable file found on the mediastore is already in the library.

Event data: The mmsync_first_fid_data_t structure, which contains:

  • the ID of the first file
  • the synchronization operation ID
  • the timestamp field, which indicates the time the files pass was started

DB tables updated: None.

MMSYNC_EVENT_BUFFER_TOO_SMALL

The event buffer on the client side is too small to fetch events from mm-sync. The data indicates the next message size and the full queue size.

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 sizes (in bytes) of the first queued event and all queued events.

DB tables updated: None.

MMSYNC_EVENT_MS_SYNC_FOLDER_TRIM_COMPLETE

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 once 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 ID of the folder in which the event occurred
  • the current synchronization pass, which is always 1 (for the files pass)
  • the number of files, subfolders, and playlists deleted from the folder during this pass
  • the timestamp field, which is the start time of the synchronization operation
  • the synchronization operation ID

DB tables updated: files, folders, playlists, and playlist_entries.

Library:

mmsyncclient

Description:

The mm-sync event types, which can be general or synchronization events.