mme_mediacopier_add_with_metadata()

Add files to the copy queue, specifying strings for unknown metadata

Synopsis:

#include <mme/mme.h>

int mme_mediacopier_add_with_metadata( mme_hdl_t *hdl,
                                       mme_mediacopier_info_t *copyinfo,
                                       const char *statement,
                                       uint32_t flags,
                                       const char *unknown_album,
                                       const char *unknown_artist );

Arguments:

hdl
An MME connection handle.
copyinfo
A pointer to a mme_mediacopier_info_t structure that contains information about the copy operation.
statement
An SQL statement that selects the fids that you want to encode.
flags
Flags affecting the copy operation. See Mediacopier flags below.
unknown_album
A pointer to a text string to add to the file metadata if the album is not known.
unknown_artist
A pointer to a text string to add to the file metadata if the artist is not known.

Library:

mme

Description:

The function mme_mediacopier_add_with_metadata() prepares a media copying or ripping operation and adds specified strings when the artist or album is not known. This function behaves exactly like mme_mediacopier_add(), except for the added functionality required to add the string for unknown metadata.

This function updates metadata if:

The function mme_mediacopier_add_with_metadata() updates the metadata both in the MME library table entry for the destination file, and in the destination file itself. This behavior ensures that the metadata added to the destination file is maintained, even in the event that the MME database is lost.

To specify metadata for destination files whose album or artist is not known, use the unknown_album and unknown_artist fields, specifying the strings to insert as metadata, and including the $MSIDENTIFIER template variable in the strings to ensure that each file is uniquely identified. See $MSIDENTIFIER below.

Determining destination file and folder names

Calls to mme_mediacopier_add_with_metadata() determine destination file and folder names as follows:

Mediacopier flags

Media copying and ripping uses the flags argument to determine media copying and ripping behavior. Possible values are combinations of:

Flag Value Description
MME_MEDIACOPIER_COPYADD_NONE 0x0000 Copy or rip directly to a destination folder. Obsolete; not supported.
MME_MEDIACOPIER_COPYADD_PRESERVE_PATH 0x0001 Preserve the original folder structure for copied or ripped files. Create folders as required. Obsolete; not supported.
MME_MEDIACOPIER_USE_DEFAULT_FILENAME 0x0002 Use the default destination filename set in the MME configuration file.
MME_MEDIACOPIER_USE_METADATA 0x0004 Use the specified metadata; do not use defaults.
MME_MEDIACOPIER_USE_DEFAULT_FOLDERNAME 0x0008 Use the default destination folder name set in the MME configuration file.

For more information about default destination files and folders, see Configuration elements for the media copy and ripping destination in the MME Configuration Guide chapter Configuring Media Copying and Ripping.

$MSIDENTIFIER

The $MSIDENTIFIER template variable is set to the value of the identifier field in the mediastores table. Adding it to the string written into a destination file's unknown_* fields ensures that the destinatation file is always correctly associated with its mediastore.

Events

None delivered.

Blocking and validation

Full validation of data; all arguments are checked before the call returns.

Returns:

0.
Success.
-1
An error occurred (errno is set).

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

METADATA_*, mme_mediacopier_add(), mme_mediacopier_cleanup(), mme_mediacopier_clear(), mme_mediacopier_disable(), mme_mediacopier_enable(), mme_mediacopier_get_status(), mme_mediacopier_remove(), mme_mediacopier_info_t