Cataloger
[Content Management]

Detailed Description

Media Selector Cataloger API

Please be aware that most - not all - of these methods work by communicating with mediacatd via IPC. Some return 'immediately', regardless of whether the operations succeeds or fails, and only return IPC errors; others block until the requested operation is complete, and can return actual success or failure codes.

Modules

Standard registered directories

Convenient, 'portable' synonyms for the standard registered directories.

Messages sent by the media cataloger daemon

Messages that you may want to handle.

Messages sent to the media cataloger daemon

Details you might be better off not knowing ...

Extractor Plugins

Information about implementing cataloger extractor plugins.

Data Structures

struct _AlpNotifyEventFileRenamed

struct _AlpNotifyEventIndexFileResults

struct _AlpNotifyEventIndexFileResultsHeader

struct _AlpNotifyEventUnindexFileResults

struct _AlpNotifyEventUnindexFileResultsHeader

Defines

#define ALP_MS_CAT_INDEX_FILE_RESULTS_VERSION_1PT0   0x00010000

Version constant for the AlpNotifyEventIndexFileResultsHeader struct, sent in an ALP_NOTIFY_EVENT_MS_INDEX_FILE message.

#define ALP_MS_CAT_UNINDEX_FILE_RESULTS_VERSION_1PT0   0x00010000

#define ALP_NOTIFY_EVENT_MS_RENAME_FILE   ALP_MS_EVENT_PREFIX "rename_file"

The event (optionally) raised by the alp_ms_cat_rename_file() method.

#define FILE_RENAMED_NOTIFICATION_VERSION_1PT0   0x00010000

Version constant for the AlpNotifyEventFileRenamed struct, sent by the alp_ms_cat_rename_file() method.

Typedefs

typedef int(* alp_ms_cat_file_copy_callback )(const char *destination_filename, const char *source_filename, int64_t bytes_copied, int64_t total_bytes, void *data)

Optional, progress reporting callback for alp_ms_cat_file_copy_callback.

typedef void * AlpMSRegDirH

typedef _AlpNotifyEventFileRenamed AlpNotifyEventFileRenamed

This is the structure of a ALP_NOTIFY_EVENT_MS_RENAME_FILE, optionallly sent by the alp_ms_cat_rename_file() method.

typedef _AlpNotifyEventIndexFileResults AlpNotifyEventIndexFileResults

An ALP_NOTIFY_EVENT_MS_INDEX_FILE message contains this in its details pointer.

typedef _AlpNotifyEventIndexFileResultsHeader AlpNotifyEventIndexFileResultsHeader

The fixed-size part of an AlpNotifyEventIndexFileResults struct.

typedef _AlpNotifyEventUnindexFileResults AlpNotifyEventUnindexFileResults

An ALP_NOTIFY_EVENT_MS_UNINDEX_FILE message contains this in its details pointer.

typedef _AlpNotifyEventUnindexFileResultsHeader AlpNotifyEventUnindexFileResultsHeader

The fixed-size part of an AlpNotifyEventUnindexFileResults struct.

Enumerations

enum AlpMsCatIndexFileStatus {
  ALP_MS_CAT_IFS_SUCCESS, ALP_MS_CAT_IFS_FILE_DOES_NOT_EXIST, ALP_MS_CAT_IFS_NOT_IN_REGISTERED_DIRECTORY, ALP_MS_CAT_IFS_INDEXING_ERROR,
  ALP_MS_CAT_IFS_DATABASE_ERROR
}

enum AlpMsCatUnindexFileStatus { ALP_MS_CAT_UFS_SUCCESS, ALP_MS_CAT_UFS_NOT_INDEXED, ALP_MS_CAT_UFS_UNINDEXING_ERROR, ALP_MS_CAT_UFS_FILE_DOES_NOT_EXIST }

Functions

alp_status_t alp_ms_cat_copy_file (const char *new_filename, const char *existing_filename, alp_ms_cat_file_copy_callback callback, void *data)

Copy a single file and its metadata to a new location, optionally with a new filename.

bool alp_ms_cat_extension_supported (const char *extension)

Checks to see if a certain media format is indexed by The Media Selector.

alp_status_t alp_ms_cat_get_registered_begin (AlpMSRegDirH *handle)

Enumerates over the registered directories, initializes enumeration.

alp_status_t alp_ms_cat_get_registered_end (AlpMSRegDirH handle)

Cleans up after enumeration over the registered directories.

alp_status_t alp_ms_cat_get_registered_next_dir (AlpMSRegDirH handle, char **directory)

Enumerates over the registered directories, gets next entry.

alp_status_t alp_ms_cat_index_file (const char *filename)

Adds a single file to catalog, and extracts its metadata.

alp_status_t alp_ms_cat_register_directory (const char *path)

Adds path to Cataloger media paths and does a recursive scan for media files.

alp_status_t alp_ms_cat_rename_file (const char *new_filename, const char *existing_url, const char *notification_app)

Rename a single file and its metadata, optionally broadcasting an ALP_NOTIFY_EVENT_MS_RENAME_FILE event that contains an AlpNotifyEventFileRenamed structure with the original URL and the new filename.

alp_status_t alp_ms_cat_unindex_file (const char *filename)

Removes a single file and its metadata from catalog.

alp_status_t alp_ms_cat_unregister_directory (const char *path)

Removes path from cataloger db, and removes all data (from metadata.db) about files in (or under) this directory.

alp_status_t alp_ms_cat_update (const char *path)

Call when the contents of a registered directory change, to update the catalog. (When you add a single file, alp_ms_cat_index_file is significantly faster than alp_ms_cat_update().).

Define Documentation

#define ALP_MS_CAT_INDEX_FILE_RESULTS_VERSION_1PT0 0x00010000

Version constant for the AlpNotifyEventIndexFileResultsHeader struct, sent in an ALP_NOTIFY_EVENT_MS_INDEX_FILE message.

#define ALP_MS_CAT_UNINDEX_FILE_RESULTS_VERSION_1PT0 0x00010000

Version constant for the AlpNotifyEventUnindexFileResultsHeader struct, sent in an ALP_NOTIFY_EVENT_MS_UNINDEX_FILE message

#define ALP_NOTIFY_EVENT_MS_RENAME_FILE ALP_MS_EVENT_PREFIX "rename_file"

The event (optionally) raised by the alp_ms_cat_rename_file() method.

#define FILE_RENAMED_NOTIFICATION_VERSION_1PT0 0x00010000

Version constant for the AlpNotifyEventFileRenamed struct, sent by the alp_ms_cat_rename_file() method.

Typedef Documentation

typedef int(* alp_ms_cat_file_copy_callback)(const char *destination_filename, const char *source_filename, int64_t bytes_copied, int64_t total_bytes, void *data)

Optional, progress reporting callback for alp_ms_cat_file_copy_callback.

Parameters:

[in] destination_filename The name of the file being created

[in] source_filename The name of the file being copied

[in] bytes_copied Bytes copied so far (current size of destination_filename)

[in] total_bytes Total bytes to copy (size of source_filename)

[in] data Arbitrary use data - useful for calling object-oriented routines

Returns:
Any non-zero result aborts the copy operation, and alp_ms_cat_file_copy_callback returns ALP_STATUS_MS_CAT_USER_ABORT.

typedef void* AlpMSRegDirH

typedef struct _AlpNotifyEventFileRenamed AlpNotifyEventFileRenamed

This is the structure of a ALP_NOTIFY_EVENT_MS_RENAME_FILE, optionallly sent by the alp_ms_cat_rename_file() method.

typedef struct _AlpNotifyEventIndexFileResults AlpNotifyEventIndexFileResults

An ALP_NOTIFY_EVENT_MS_INDEX_FILE message contains this in its details pointer.

typedef struct _AlpNotifyEventIndexFileResultsHeader AlpNotifyEventIndexFileResultsHeader

The fixed-size part of an AlpNotifyEventIndexFileResults struct.

typedef struct _AlpNotifyEventUnindexFileResults AlpNotifyEventUnindexFileResults

An ALP_NOTIFY_EVENT_MS_UNINDEX_FILE message contains this in its details pointer.

typedef struct _AlpNotifyEventUnindexFileResultsHeader AlpNotifyEventUnindexFileResultsHeader

The fixed-size part of an AlpNotifyEventUnindexFileResults struct.

Enumeration Type Documentation

enum AlpMsCatIndexFileStatus

alp_ms_cat_index_file() result codes: contained in an AlpNotifyEventIndexFileResults struct that's sent in an ALP_NOTIFY_EVENT_MS_INDEX_FILE message
Enumerator:

ALP_MS_CAT_IFS_SUCCESS file indexed successfully (does not imply extractor success)

ALP_MS_CAT_IFS_FILE_DOES_NOT_EXIST can only index files that actually exist

ALP_MS_CAT_IFS_NOT_IN_REGISTERED_DIRECTORY file exists, but is not in a registered directory

ALP_MS_CAT_IFS_INDEXING_ERROR internal error, indexing existing file in registered directory

ALP_MS_CAT_IFS_DATABASE_ERROR internal error, couldn't open appropriate database

enum AlpMsCatUnindexFileStatus

alp_ms_cat_unindex_file() result codes: contained in an AlpNotifyEventUnindexFileResultsHeader struct that's sent in an ALP_NOTIFY_EVENT_MS_UNINDEX_FILE message
Enumerator:

ALP_MS_CAT_UFS_SUCCESS file unindexed successfully

ALP_MS_CAT_UFS_NOT_INDEXED can only unindex files that are actually indexed

ALP_MS_CAT_UFS_UNINDEXING_ERROR internal error, unindexing existing file

ALP_MS_CAT_UFS_FILE_DOES_NOT_EXIST file and/or path does not exist; fell back to alp_ms_cat_update() on closest existing directory. (Please note that this is an asynchronous operation, and receieving an ALP_MS_CAT_UFS_FILE_DOES_NOT_EXIST does not necessarily mean your file has been unindexed yet.)

Function Documentation

alp_status_t alp_ms_cat_copy_file ( const char * new_filename,

const char * existing_filename,

alp_ms_cat_file_copy_callback callback,

void * data

)

Copy a single file and its metadata to a new location, optionally with a new filename.

Parameters:

[in] new_filename The new path and filename

[in] existing_filename The file to copy

[in] callback Optional progress callback - may be NULL. Non-zero return aborts copy.

[in] data Arbitrary data, passed to the optional callback

Returns:
Returns IPC errors if there are problems, otherwise ALP_STATUS_OK on success. Also returns errors if existing_filename does not exist, or new_filename is illegal.
ALP_STATUS_MS_CAT_USER_ABORT if optional callback returns non-zero.

Note:
This method does the copy in the calling process, then passes a request to mediacatd to copy the metadata (and adjust the copy's ownership and timestamps.) The optional callback will be called at least once (ie, it is always called on copy-completion, even if the source file is smaller than the copy buffer size) with filename and file size information: it is up to the calling application to map this to percent complete.
The callback will not be called to signal metadata copy completion, but this method blocks until it has copied the file AND mediacatd has copied the metadata.

bool alp_ms_cat_extension_supported ( const char * extension )

Checks to see if a certain media format is indexed by The Media Selector.

Parameters:

[in] extension The file extension to check.

Returns:
'true' if the extension is supported/indexed, 'false' if not.

alp_status_t alp_ms_cat_get_registered_begin ( AlpMSRegDirH * handle )

Enumerates over the registered directories, initializes enumeration.

Parameters:

[out] handle The address of a AlpMSRegDirH to be initialized by this method. The (non-NULL) handle will be used in all subsequent related calls. (Handle will be NULL if this method returns an error code.)

Returns:
May return database errors if there is a problem. Returns ALP_STATUS_OK on success. Sets handle to NULL on error.

alp_status_t alp_ms_cat_get_registered_end ( AlpMSRegDirH handle )

Cleans up after enumeration over the registered directories.

Parameters:

[in] handle The handle initialized by alp_ms_cat_get_registered_begin().

Returns:
Always returns ALP_STATUS_OK. Will crash if passed in an invalid handle.

alp_status_t alp_ms_cat_get_registered_next_dir ( AlpMSRegDirH handle,

char ** directory

)

Enumerates over the registered directories, gets next entry.

Parameters:

[in] handle The handle initialized by alp_ms_cat_get_registered_begin().

[out] directory An address of a char* that will be filled to point to a direcory path. The caller must not free this variable, it will be deallocated when alp_ms_cat_get_registered_end() is called.

Returns:
Will return ALP_STATUS_CAT_DB_DONE when all dirs have been returned.

alp_status_t alp_ms_cat_index_file ( const char * filename )

Adds a single file to catalog, and extracts its metadata.

Parameters:

[in] filename The fully qualified name of the file to catalog

Returns:
Returns IPC errors if there are problems, otherwise ALP_STATUS_OK on IPC success. All status-returns are via ALP_NOTIFY_EVENT_MS_INDEX_FILE broadcast from ALP_MEDIASELECTOR_APP_ID: the details pointer points to a (variable-length) AlpNotifyEventIndexFileResults structure.

alp_status_t alp_ms_cat_register_directory ( const char * path )

Adds path to Cataloger media paths and does a recursive scan for media files.

Parameters:

[in] path The directory to catalog. Should always be a path on the device - never a path on the card. (Card mounts are implicitly registered. Attempting to register a card directory will return an error code without doing any damage ... but this just wastes time.)

Returns:
Returns IPC errors if there are problems, otherwise ALP_STATUS_OK on success.
ALP_STATUS_MS_CAT_INVALID_PATH If path parameter is 1) NULL, 2) not rooted at /, 3) not an actual directory, or 4) is (or is under) a mounted card.

Note:
Registration is recursive: If /foo is registered, so is /foo/bar. Explicitly registering both /foo and foo/bar will cause files in /foo/bar to be cataloged twice! Please note that /home is an alias for /var/home (which is registered): do not register any directories under either /home or /var/home.

alp_status_t alp_ms_cat_rename_file ( const char * new_filename,

const char * existing_url,

const char * notification_app

)

Rename a single file and its metadata, optionally broadcasting an ALP_NOTIFY_EVENT_MS_RENAME_FILE event that contains an AlpNotifyEventFileRenamed structure with the original URL and the new filename.

Parameters:

[in] new_filename The new filename. This may not have any path component. An extension is optional, but must match the existing_url if present.

[in] existing_url The file to rename. (See alp_mf_get_file_url().)

[in] notification_app Name of the notifying app. (NULL or "" means no-notification.)

Returns:
Returns IPC errors if there are problems, otherwise ALP_STATUS_OK on success.
ALP_STATUS_MF_INVALID_PARAM If the url passed in is not valid.
ALP_STATUS_MS_CAT_BAD_PARAMETER If new_filename is NULL, "", or contains a '/' character
ALP_STATUS_MS_CAT_INVALID_PATH If new_filename is neither a valid URL nor a valid filename
ALP_STATUS_MS_CAT_FILE_NOT_FOUND If existing_url does not refer to a cataloged file
ALP_STATUS_MS_CAT_TARGET_FILE_EXISTS There is already a file named new_filename in the same directory as existing_url
ALP_STATUS_MS_CAT_NOT_SUPPORTED If new_filename and existing_url have a different extension

alp_status_t alp_ms_cat_unindex_file ( const char * filename )

Removes a single file and its metadata from catalog.

Parameters:

[in] filename The fully qualified name of the file that will be deleted.

Note:

This operation is much more efficient if the file exists when this method is called! If the file has already been deleted, alp_ms_cat_unindex_file() falls back to calling alp_ms_cat_update() on the lowest surviving 'leaf' directory - calling alp_ms_cat_update() is more efficient.

All status-returns are via ALP_NOTIFY_EVENT_MS_UNINDEX_FILE broadcast from ALP_MEDIASELECTOR_APP_ID: the details pointer points to a (variable length) AlpNotifyEventUnindexFileResults structure.

Returns:
IPC errors if there are IPC problems.
ALP_STATUS_OK if files exists and there are no IPC errors.

alp_status_t alp_ms_cat_unregister_directory ( const char * path )

Removes path from cataloger db, and removes all data (from metadata.db) about files in (or under) this directory.

Parameters:

[in] path The directory to stop monitoring.

Returns:
Returns IPC errors if there are problems, otherwise ALP_STATUS_OK on success.

alp_status_t alp_ms_cat_update ( const char * path )

Call when the contents of a registered directory change, to update the catalog. (When you add a single file, alp_ms_cat_index_file is significantly faster than alp_ms_cat_update().).

Parameters:

[in] path The directory to update.

Returns:
May return IPC errors if the cataloger daemon cannot be reached. Returns ALP_STATUS_OK on success.

Note:
It's OK to update a subdirectory of a registered directory, but this must be obvious to a term-by-term string comparison. That is, since "/var/home" is registered, it's OK to update "/var/home/MyData". (The path parameter is canonicized, so it's safe to use soft links like "/home" (which links to "/var/home") but do *not* use hard links to registered directories.)

Generated on Wed Jul 30 07:06:42 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation


Modules
	Standard registered directories
	Convenient, 'portable' synonyms for the standard registered directories.
	Messages sent by the media cataloger daemon
	Messages that you may want to handle.
	Messages sent to the media cataloger daemon
	Details you might be better off not knowing ...
	Extractor Plugins
	Information about implementing cataloger extractor plugins.
Data Structures
struct	_AlpNotifyEventFileRenamed
struct	_AlpNotifyEventIndexFileResults
struct	_AlpNotifyEventIndexFileResultsHeader
struct	_AlpNotifyEventUnindexFileResults
struct	_AlpNotifyEventUnindexFileResultsHeader
Defines
#define	ALP_MS_CAT_INDEX_FILE_RESULTS_VERSION_1PT0 0x00010000
	Version constant for the `AlpNotifyEventIndexFileResultsHeader` struct, sent in an `ALP_NOTIFY_EVENT_MS_INDEX_FILE` message.
#define	ALP_MS_CAT_UNINDEX_FILE_RESULTS_VERSION_1PT0 0x00010000
#define	ALP_NOTIFY_EVENT_MS_RENAME_FILE ALP_MS_EVENT_PREFIX "rename_file"
	The event (optionally) raised by the alp_ms_cat_rename_file() method.
#define	FILE_RENAMED_NOTIFICATION_VERSION_1PT0 0x00010000
	Version constant for the `AlpNotifyEventFileRenamed` struct, sent by the alp_ms_cat_rename_file() method.
Typedefs
typedef int(*	alp_ms_cat_file_copy_callback )(const char destination_filename, const char source_filename, int64_t bytes_copied, int64_t total_bytes, void *data)
	Optional, progress reporting callback for `alp_ms_cat_file_copy_callback`.
typedef void *	AlpMSRegDirH
typedef _AlpNotifyEventFileRenamed	AlpNotifyEventFileRenamed
	This is the structure of a ALP_NOTIFY_EVENT_MS_RENAME_FILE, optionallly sent by the alp_ms_cat_rename_file() method.
typedef _AlpNotifyEventIndexFileResults	AlpNotifyEventIndexFileResults
	An `ALP_NOTIFY_EVENT_MS_INDEX_FILE` message contains this in its details pointer.
typedef _AlpNotifyEventIndexFileResultsHeader	AlpNotifyEventIndexFileResultsHeader
	The fixed-size part of an `AlpNotifyEventIndexFileResults` struct.
typedef _AlpNotifyEventUnindexFileResults	AlpNotifyEventUnindexFileResults
	An `ALP_NOTIFY_EVENT_MS_UNINDEX_FILE` message contains this in its details pointer.
typedef _AlpNotifyEventUnindexFileResultsHeader	AlpNotifyEventUnindexFileResultsHeader
	The fixed-size part of an `AlpNotifyEventUnindexFileResults` struct.
Enumerations
enum	AlpMsCatIndexFileStatus { ALP_MS_CAT_IFS_SUCCESS, ALP_MS_CAT_IFS_FILE_DOES_NOT_EXIST, ALP_MS_CAT_IFS_NOT_IN_REGISTERED_DIRECTORY, ALP_MS_CAT_IFS_INDEXING_ERROR, ALP_MS_CAT_IFS_DATABASE_ERROR }
enum	AlpMsCatUnindexFileStatus { ALP_MS_CAT_UFS_SUCCESS, ALP_MS_CAT_UFS_NOT_INDEXED, ALP_MS_CAT_UFS_UNINDEXING_ERROR, ALP_MS_CAT_UFS_FILE_DOES_NOT_EXIST }
Functions
alp_status_t	alp_ms_cat_copy_file (const char new_filename, const char existing_filename, alp_ms_cat_file_copy_callback callback, void *data)
	Copy a single file and its metadata to a new location, optionally with a new filename.
bool	alp_ms_cat_extension_supported (const char *extension)
	Checks to see if a certain media format is indexed by The Media Selector.
alp_status_t	alp_ms_cat_get_registered_begin (AlpMSRegDirH *handle)
	Enumerates over the registered directories, initializes enumeration.
alp_status_t	alp_ms_cat_get_registered_end (AlpMSRegDirH handle)
	Cleans up after enumeration over the registered directories.
alp_status_t	alp_ms_cat_get_registered_next_dir (AlpMSRegDirH handle, char **directory)
	Enumerates over the registered directories, gets next entry.
alp_status_t	alp_ms_cat_index_file (const char *filename)
	Adds a single file to catalog, and extracts its metadata.
alp_status_t	alp_ms_cat_register_directory (const char *path)
	Adds path to Cataloger media paths and does a recursive scan for media files.
alp_status_t	alp_ms_cat_rename_file (const char new_filename, const char existing_url, const char *notification_app)
	Rename a single file and its metadata, optionally broadcasting an ALP_NOTIFY_EVENT_MS_RENAME_FILE event that contains an AlpNotifyEventFileRenamed structure with the original URL and the new filename.
alp_status_t	alp_ms_cat_unindex_file (const char *filename)
	Removes a single file and its metadata from catalog.
alp_status_t	alp_ms_cat_unregister_directory (const char *path)
	Removes path from cataloger db, and removes all data (from metadata.db) about files in (or under) this directory.
alp_status_t	alp_ms_cat_update (const char *path)
	Call when the contents of a registered directory change, to update the catalog. (When you add a single file, alp_ms_cat_index_file is significantly faster than alp_ms_cat_update().).

Cataloger [Content Management]

Detailed Description

Modules

Data Structures

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Cataloger
[Content Management]