© 2013 Samsung Electronics Co., Ltd. All rights reserved.
API to discover and manage images, videos, music and the other contents.
This API provides functionality to discover contents (such as images, videos, music or the other) that are available on the device. It is possible to search for specific contents using filters. The API also supports setting attributes of specific contents.
For more information on the Content features, see Content Guide.
Interface | Method |
---|---|
ContentManagerObject | |
ContentManager | void update(Content content) void updateBatch(Content[] contents, SuccessCallback? successCallback, ErrorCallback? errorCallback) void getDirectories(ContentDirectoryArraySuccessCallback successCallback, ErrorCallback? errorCallback) void find(ContentArraySuccessCallback successCallback, ErrorCallback? errorCallback, ContentDirectoryId? directoryId, AbstractFilter? filter, SortMode? sortMode, unsigned long? count, unsigned long? offset) void scanFile(DOMString contentURI, ContentScanSuccessCallback? successCallback, ErrorCallback? errorCallback) void setChangeListener(ContentChangeCallback changeCallback) void unsetChangeListener() |
ContentArraySuccessCallback | void onsuccess(Content[] contents) |
ContentDirectoryArraySuccessCallback | void onsuccess(ContentDirectory[] directories) |
ContentScanSuccessCallback | void onsuccess(DOMString contentURI) |
ContentChangeCallback | void oncontentadded(Content content) void oncontentupdated(Content content) void oncontentremoved(ContentId id) |
ContentDirectory | |
Content | |
VideoContent | |
AudioContentLyrics | |
AudioContent | |
ImageContent |
enum ContentDirectoryStorageType { "INTERNAL", "EXTERNAL" };
Defines whether a content directory is stored in the internal or external storage (such as a removable memory card).
enum ContentType { "IMAGE", "VIDEO", "AUDIO", "OTHER" };
Defines a type of content (image, video, audio and the other types).
"OTHER" type is added since 2.1.
enum AudioContentLyricsType { "SYNCHRONIZED", "UNSYNCHRONIZED" };
Defines whether a lyric supplied with an audio file is time-synchronized or not.
enum ImageContentOrientation { "NORMAL", "FLIP_HORIZONTAL", "ROTATE_180", "FLIP_VERTICAL", "TRANSPOSE", "ROTATE_90", "TRANSVERSE", "ROTATE_270" };
Defines an orientation of an image.
Content identifier.
typedef DOMString ContentId;
Content directory identifier.
typedef DOMString ContentDirectoryId;
Defines what is instantiated in the webapis object.
[NoInterfaceObject] interface ContentManagerObject { readonly attribute ContentManager content; };
WebAPIs implements ContentManagerObject;
There will be a webapis.content object that allows accessing the functionality of the content module.
ContentManager interface that provides operations to retrieve and manipulate contents.
[NoInterfaceObject] interface ContentManager { void update(Content content) raises(WebAPIException); void updateBatch(Content[] contents, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getDirectories(ContentDirectoryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(ContentArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ContentDirectoryId? directoryId, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? count, optional unsigned long? offset) raises(WebAPIException); void scanFile(DOMString contentURI, optional ContentScanSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setChangeListener(ContentChangeCallback changeCallback) raises(WebAPIException); void unsetChangeListener() raises(WebAPIException); };
update
Changes attributes of a content in the content database, synchronously.
void update(Content content);
When an application has changed some attributes in a content, this method allows writing it back to the content database.
The editableAttributes in content interface indicates which attributes can be changed. This API does not support updating the metadata of the original file.
with error type UnknownError in any other error case.
with error type SecurityError, if the client does not have the permission to add alarms.
with error type NotSupportedError, if this feature is not supported.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
// The following example changes a description. // Assume the content is a Content object as a result of find method. // Check the description is editable, and then set a description. if (content.editableAttributes.indexOf("description") >= 0) { content.description = "Sample content"; } webapis.content.update(content);
updateBatch
Changes attributes of a number of contents in the content database, asynchronously.
void updateBatch(Content[] contents, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
When an application has changed any attributes in array of content, this method allows writing them back to the content database.
The errorCallback is launched with these error types:
The editableAttributes in content interface indicates which attributes can be changed. This API does not support updating the metadata of the original file.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
// The following example increases rating of an content by 1 function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function successCB() { console.log('Attributes set successfully'); } // Assume the content is a Content object as a result of find method. // Check the rating is editable, and then increase by 1. if (content.editableAttributes.indexOf("rating") >= 0) { content.rating++; } webapis.content.updateBatch([content], successCB, errorCB);
getDirectories
Gets a list of content directories.
void getDirectories(ContentDirectoryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);
This method returns (via callback) a list of content directory objects. To obtain a list of contents in a specific directory, use find() method with the directory ID.
The errorCallback is launched with these error types:
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
// The following example retrieves content directories in the storage. function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function printDirectory(directory, index, directories) { console.log('directoryURI: ' + directory.directoryURI + ' Title: ' + directory.title); } function getDirectoriesCB(directories) { directories.forEach(printDirectory); } webapis.content.getDirectories(getDirectoriesCB, errorCB);
find
Finds contents that meets the search condition given by a filter
void find(ContentArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ContentDirectoryId? directoryId, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? count, optional unsigned long? offset);
This method allows searching based on a supplied filter. For more detail on AbstractFilter, refer to the WebAPIs module. The filter allows precise searching such as "return all songs by artist U2, ordered by name".
The errorCallback is launched with these error types:
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
// The following example retrieves all songs from the album "The Joshua Tree", by artist "U2", ordered by the track number. var count = 100; var offset = 0; var sortMode = new webapis.SortMode("trackNumber", "ASC"); var artistFilter = new webapis.AttributeFilter("artists", "EXACTLY", "U2"); var albumFilter = new webapis.AttributeFilter("album", "EXACTLY", "The Joshua Tree"); var filter = new webapis.CompositeFilter("INTERSECTION", [albumFilter, artistFilter]); webapis.content.find(findCB, errorCB, null, filter, sortMode, count, offset); function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function printContent(content, index, contents) { console.log('Track: ' + content.trackNumber + ' Title: ' + content.title + 'Duration: ' + content.duration + 'URL: ' + content.contentURI + 'MIME: ' + content.mimeType); } function findCB(contents) { console.log('The Joshua Tree by U2:'); contents.forEach(printContent); // Increase the offset as much as the count and then find content again. if (contents.length == count) { offset += count; webapis.content.find(findCB, errorCB, null, filter, sortMode, count, offset); } }
scanFile
Scan a file to create or update a content in the content database.
void scanFile(DOMString contentURI, optional ContentScanSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
When an application creates or updates a content, this method allows scan it to insert or update the content in the content database.
with error type UnknownError in any other error case.
with error type SecurityError, if the client does not have the permission to add alarms.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
// The following example scan 'samsung.jpg' in media directory function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function successCB(path) { console.log('scanning is completed'); } var path = "file:///opt/usr/media/samsung.jpg"; webapis.content.scanFile(path, successCB, errorCB);
setChangeListener
Sets a listener to receive notifications about content changes.
void setChangeListener(ContentChangeCallback changeCallback);
with error type UnknownError, if any other error occurs.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var listener= { oncontentadded: function(content) { console.log(content.contentURI + ' content is added'); }, oncontentupdated: function(content) { console.log(content.contentURI + ' content is updated'); }, oncontentremoved: function(id) { console.log(id + ' is removed'); } }; // Registers to be notified when the content changes webapis.content.setChangeListener(listener);
unsetChangeListener
Unset the listener to stop receiving notification for content changes.
void unsetChangeListener();
with error type UnknownError if any other error occurs.
with error type SecurityError, if the functionality is not allowed.
webapis.content.unsetChangeListener();
The callback function used to return a list of content objects.
[Callback=FunctionOnly, NoInterfaceObject] interface ContentArraySuccessCallback { void onsuccess(Content[] contents); };
onsuccess
Called when the list of content is retrieved successfully.
void onsuccess(Content[] contents);
The callback function used to return a list of ContentDirectory objects.
[Callback=FunctionOnly, NoInterfaceObject] interface ContentDirectoryArraySuccessCallback { void onsuccess(ContentDirectory[] directories); };
onsuccess
Called when the list of directory is retrieved successfully.
void onsuccess(ContentDirectory[] directories);
The callback function used to return a content to scan has been completed.
[Callback=FunctionOnly, NoInterfaceObject] interface ContentScanSuccessCallback { void onsuccess(DOMString contentURI); };
onsuccess
Called when the scanning has been completed.
void onsuccess(DOMString contentURI);
This interface specifies a set of methods that will be invoked every time a content change occurs.
[Callback, NoInterfaceObject] interface ContentChangeCallback { void oncontentadded(Content content); void oncontentupdated(Content content); void oncontentremoved(ContentId id); };
oncontentadded
Called when content is added.
void oncontentadded(Content content);
oncontentupdated
Called when content is updated.
void oncontentupdated(Content content);
oncontentremoved
Called when content is removed.
void oncontentremoved(ContentId id);
The content directory interface that provides access to properties of a content directory.
[NoInterfaceObject] interface ContentDirectory { readonly attribute ContentDirectoryId id; readonly attribute DOMString directoryURI; readonly attribute DOMString title; readonly attribute ContentDirectoryStorageType storageType; readonly attribute Date? modifiedDate; };
readonly
ContentDirectoryId id
The opaque content directory ID.
readonly
DOMString directoryURI
The directory path on the device.
readonly
DOMString title
The directory name.
readonly
ContentDirectoryStorageType storageType
The type of a device storage.
readonly
Date? modifiedDate
The directory modification date.
The content interface that provides access to properties of content.
[NoInterfaceObject] interface Content { readonly attribute DOMString[] editableAttributes; readonly attribute ContentId id; attribute DOMString name; readonly attribute ContentType type; readonly attribute DOMString mimeType; readonly attribute DOMString title; readonly attribute DOMString contentURI; readonly attribute DOMString[]? thumbnailURIs; readonly attribute Date? releaseDate; readonly attribute Date? modifiedDate; readonly attribute unsigned long size; attribute DOMString? description; attribute unsigned long rating; };
readonly
DOMString[] editableAttributes
The list of attributes that can be written back to the local backend using update or updateBatch method.
readonly
ContentId id
The opaque content ID.
DOMString name
The name of content. The initial value is the file name of the content.
readonly
ContentType type
The content type.
readonly
DOMString mimeType
The content MIME type.
readonly
DOMString title
The content title.
readonly
DOMString contentURI
The URI that can be used to access the content.
readonly
DOMString[]? thumbnailURIs
The array of content thumbnails URIs.
readonly
Date? releaseDate
The date when a content has been released to the public. If only the release year is known, then the day and month are set to January 1st.
readonly
Date? modifiedDate
The date when this content has last been modified.
readonly
unsigned long size
The file size of the content in bytes.
DOMString? description
The content description.
unsigned long rating
The content rating (value varies from 0 to 10).
The interface that extends a basic content object with video-specific attributes.
[NoInterfaceObject] interface VideoContent : Content { attribute SimpleCoordinates? geolocation; readonly attribute DOMString? album; readonly attribute DOMString[]? artists; readonly attribute unsigned long duration; readonly attribute unsigned long width; readonly attribute unsigned long height; };
SimpleCoordinates? geolocation
The geographical location where the video was made.
readonly
DOMString? album
The album name to which the video belongs.
readonly
DOMString[]? artists
The list of artists that created the video.
readonly
unsigned long duration
The video duration in milliseconds.
readonly
unsigned long width
The width of the video in pixels.
readonly
unsigned long height
The height of the video in pixels.
The interface that provides lyrics for music.
[NoInterfaceObject] interface AudioContentLyrics { readonly attribute AudioContentLyricsType type; readonly attribute unsigned long[] timestamps; readonly attribute DOMString[] texts; };
readonly
AudioContentLyricsType type
The type of lyrics: whether they are synchronized with the music or not.
readonly
unsigned long[] timestamps
The array of timestamps in milliseconds for lyrics.
If the lyrics are not synchronized (if there is no time information for the lyrics) the array is undefined.
readonly
DOMString[] texts
The array of lyric snippets.
If the lyrics are not synchronized, the array has only one member with full lyrics.
The interface that extends a basic content object with audio-specific attributes.
[NoInterfaceObject] interface AudioContent : Content { readonly attribute DOMString? album; readonly attribute DOMString[]? genres; readonly attribute DOMString[]? artists; readonly attribute DOMString[]? composers; readonly attribute AudioContentLyrics? lyrics; readonly attribute DOMString? copyright; readonly attribute unsigned long bitrate; readonly attribute unsigned short? trackNumber; readonly attribute unsigned long duration; };
readonly
DOMString? album
The album name that the audio belongs to.
readonly
DOMString[]? genres
The list of genres that the audio belongs to.
readonly
DOMString[]? artists
The list of artists that created the audio.
readonly
DOMString[]? composers
The list of composers for the music.
readonly
AudioContentLyrics? lyrics
The lyrics to the song that is contained in the audio.
readonly
DOMString? copyright
The copyright information.
readonly
unsigned long bitrate
The audio bitrate in bits per second. By default, this value is 0.
readonly
unsigned short? trackNumber
The track number if the audio belongs to an album.
readonly
unsigned long duration
The audio duration in milliseconds.
The interface that extends a basic content object with image-specific attributes.
[NoInterfaceObject] interface ImageContent : Content { attribute SimpleCoordinates? geolocation; readonly attribute unsigned long width; readonly attribute unsigned long height; attribute ImageContentOrientation orientation; };
SimpleCoordinates? geolocation
The geographical location where the image has been made.
readonly
unsigned long width
The width of the Image in pixels.
readonly
unsigned long height
The height of the Image in pixels.
ImageContentOrientation orientation
Information about image orientation.
module Content { enum ContentDirectoryStorageType { "INTERNAL", "EXTERNAL" }; enum ContentType { "IMAGE", "VIDEO", "AUDIO", "OTHER" }; enum AudioContentLyricsType { "SYNCHRONIZED", "UNSYNCHRONIZED" }; enum ImageContentOrientation { "NORMAL", "FLIP_HORIZONTAL", "ROTATE_180", "FLIP_VERTICAL", "TRANSPOSE", "ROTATE_90", "TRANSVERSE", "ROTATE_270" }; typedef DOMString ContentId; typedef DOMString ContentDirectoryId; [NoInterfaceObject] interface ContentManagerObject { readonly attribute ContentManager content; }; WebAPIs implements ContentManagerObject; [NoInterfaceObject] interface ContentManager { void update(Content content) raises(WebAPIException); void updateBatch(Content[] contents, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getDirectories(ContentDirectoryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(ContentArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ContentDirectoryId? directoryId, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? count, optional unsigned long? offset) raises(WebAPIException); void scanFile(DOMString contentURI, optional ContentScanSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setChangeListener(ContentChangeCallback changeCallback) raises(WebAPIException); void unsetChangeListener() raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface ContentArraySuccessCallback { void onsuccess(Content[] contents); }; [Callback=FunctionOnly, NoInterfaceObject] interface ContentDirectoryArraySuccessCallback { void onsuccess(ContentDirectory[] directories); }; [Callback=FunctionOnly, NoInterfaceObject] interface ContentScanSuccessCallback { void onsuccess(DOMString contentURI); }; [Callback, NoInterfaceObject] interface ContentChangeCallback { void oncontentadded(Content content); void oncontentupdated(Content content); void oncontentremoved(ContentId id); }; [NoInterfaceObject] interface ContentDirectory { readonly attribute ContentDirectoryId id; readonly attribute DOMString directoryURI; readonly attribute DOMString title; readonly attribute ContentDirectoryStorageType storageType; readonly attribute Date? modifiedDate; }; [NoInterfaceObject] interface Content { readonly attribute DOMString[] editableAttributes; readonly attribute ContentId id; attribute DOMString name; readonly attribute ContentType type; readonly attribute DOMString mimeType; readonly attribute DOMString title; readonly attribute DOMString contentURI; readonly attribute DOMString[]? thumbnailURIs; readonly attribute Date? releaseDate; readonly attribute Date? modifiedDate; readonly attribute unsigned long size; attribute DOMString? description; attribute unsigned long rating; }; [NoInterfaceObject] interface VideoContent : Content { attribute SimpleCoordinates? geolocation; readonly attribute DOMString? album; readonly attribute DOMString[]? artists; readonly attribute unsigned long duration; readonly attribute unsigned long width; readonly attribute unsigned long height; }; [NoInterfaceObject] interface AudioContentLyrics { readonly attribute AudioContentLyricsType type; readonly attribute unsigned long[] timestamps; readonly attribute DOMString[] texts; }; [NoInterfaceObject] interface AudioContent : Content { readonly attribute DOMString? album; readonly attribute DOMString[]? genres; readonly attribute DOMString[]? artists; readonly attribute DOMString[]? composers; readonly attribute AudioContentLyrics? lyrics; readonly attribute DOMString? copyright; readonly attribute unsigned long bitrate; readonly attribute unsigned short? trackNumber; readonly attribute unsigned long duration; }; [NoInterfaceObject] interface ImageContent : Content { attribute SimpleCoordinates? geolocation; readonly attribute unsigned long width; readonly attribute unsigned long height; attribute ImageContentOrientation orientation; }; };