Content: Discovering Multimedia Content (Such as Images, Videos, or Music)

This tutorial demonstrates how you can retrieve content and manage items in your device local storage.

The Content API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Content API basics by learning about:

Browsing Content
Browse and search for directories and items in directories.
Managing Content
View and update item details.
Receiving Notifications on Content Changes
Receive notifications when a content item is added, updated, or deleted.
Playlist
- Creating a Playlist
  Create a new playlist and add items. Create a new playlist based on an existing playlist.
- Managing Playlists
  Retrieve all playlists. Remove a playlist.
- Managing Playlist Items
  Add, retrieve, and remove items. Change item position and order.

Task

In the Media Content task, we will walk through how to browse and manage the media directories in your application.

Browsing Content

Learning how to browse and search for content directories and content items in directories is a basic content management skill:

Retrieve the ContentManager interface instance (in mobile and wearable applications) using the tizen global object:
```
var manager = tizen.content;
```

To search for the content directories in the local device, use the getDirectories() method of the ContentManager interface. The method returns an array of ContentDirectory objects (in mobile and wearable applications).

function onDirectoryArraySuccess(directories)
{
   for (var i = 0; i < directories.length; i++)
   {
      /* Retrieve folder-specific information */
   }
}

manager.getDirectories(onDirectoryArraySuccess);

To search for the content items in all directories, use the find() method of the ContentManager interface. The method returns an array of Content objects (in mobile and wearable applications).

function onContentItemArraySuccess(contents)
{
   for (var i=0; i < contents.length; i++)
   {
      console.log(i + ":" + contents[i].type + ":" + contents[i].title + ":" + contents[i].mimeType);
   }
}

var contentType = "VIDEO";
var filter = new tizen.AttributeFilter("type", "EXACTLY", contentType);
manager.find(onContentItemArraySuccess, null, null, filter);

Note
To retrieve a specific set of content items, you can specify a content directory (with the directory ID), filter, and sorting order for the search operation through the directoryId, filter and sortMode parameters (for attributes supported in the filter, see Content Filter Attributes). In this example, the directory ID is set to null (which means that all directories are searched), the filter retrieves all content items whose type is VIDEO, and no sorting order is defined (which means that the default sorting order is used).

Note

To retrieve a specific set of content items, you can specify a content directory (with the directory ID), filter, and sorting order for the search operation through the directoryId, filter and sortMode parameters (for attributes supported in the filter, see Content Filter Attributes).

In this example, the directory ID is set to null (which means that all directories are searched), the filter retrieves all content items whose type is VIDEO, and no sorting order is defined (which means that the default sorting order is used).

Managing Content

Learning how to view content details and update them is a basic content management skill:

Retrieve theContentManager interface instance (in mobile and wearable applications) using the tizen global object, and search for the item whose details you want to update.

In the following example, the item whose title is image7.jpg is retrieved.
```
var manager = tizen.content();

var filter = new tizen.AttributeFilter("title", "EXACTLY", "image7.jpg");
manager.find(onMediaItemArraySuccess, null, null, filter);
```

In the success event handler of the find() method, view the content item details by displaying them in the console log:

function onMediaItemArraySuccess(item)
{
   if (items.length > 0) 
   {
      console.log(items[0].type + ": " + items[0].title + ": " + items[0].mimeType);
      console.log("geolocation-latitude :" + items[0].geolocation.latitude +
                  " longitude:" + items[0].geolocation.longitude);
      update(items[0]);
   }
}

To update the editable attributes of the content item, use the update() method. In the example below, the rating of the content item is increased.

function update(item)
{
   /* Checks whether the attribute is editable */
   if (item.editableAttributes.indexOf("rating") >= 0)
   {
      /* Changes an attribute */
      item.rating = 1;

      /* Updates the item */
      manager.update(item);
   }
}

To scan for the content item file, use the scanFile() method. Because scanning is not performed automatically when the content file is copied or moved, call the scanFile() method to find the file.

/* Assume the images/photo.jpg is copied to the device */
function onScanSuccessCallback(path)
{
   console.log("Scanning completed:" + path);
};

tizen.filesystem.resolve("images/photo.jpg", function(file)
                         {
                            tizen.content.scanFile(file.toURI(), onScanSuccessCallback);
                         });

Receiving Notifications on Content Changes

To create engaging applications with various content features, you must learn to receive notifications when content items are added, updated, or removed:

Define the event handlers for different notifications using the ContentChangeCallback listener instance (in mobile and wearable applications):

var listener =
{
   /* When new items are added */
   oncontentadded: function(content)
   {
      console.log(content.contentURI + " content was added");
   },

   /* When items are updated */
   oncontentupdated: function(content)
   {
      console.log(content.contentURI + " content was updated");
   },

   /* When items are deleted */
   oncontentremoved: function(id)
   {
      console.log(id + " was removed");
   }
};

Register the listener to use the defined event handlers:
```
tizen.content.setChangeListener(listener);
```
To stop the notifications, use the unsetChangeListener() method:
```
tizen.content.unsetChangeListener();
```

Creating a Playlist

Learning how to create a new playlist enables adding a playlist from your application:

To create a new empty playlist, use the createPlaylist() method of the ContentManager interface (in mobile and wearable applications):

function createSuccess(playlist)
{
   console.log("create SUCCESS");
}

tizen.content.createPlaylist("My new playlist", createSuccess);

To create a new playlist based on an existing one (basically copy the existing playlist content to a new playlist), use the createPlaylist() method, passing the source playlist as an argument:

function createSuccess(playlist)
{
   console.log("create SUCCESS");
}

tizen.content.getPlaylists(function(playlists)
{
   var existingPlaylist = playlists[0];
   tizen.content.createPlaylist("My new playlist", createSuccess, null, existingPlaylist);
});

Managing Playlists

Learning how to retrieve and remove playlists is a basic playlist management skill:

To retrieve a list of all playlists, use the getPlaylists() method of the ContentManager interface (in mobile and wearable applications):

function getPlaylistsSuccess(playlists)
{
   for (var i = 0; i < playlists.length; i++)
   {
      var cur = playlists[i];
      console.log("[" + i + "] name:" + cur.name + " number of tracks:" + cur.numberOfTracks);
   }
}
tizen.content.getPlaylists(getPlaylistsSuccess);

To remove a playlist, use the removePlaylist() method providing the ID of the playlist:

function removePlaylistSuccess()
{
   console.log("removePlaylist() is successfully done.");
}

tizen.content.getPlaylists(function(playlists)
{
   var myPlaylist = playlists[0];
   tizen.content.removePlaylist(myPlaylist.id, removePlaylistSuccess);
});

Managing Playlist Items

Learning how to manage list items is a basic playlist management skill:

To add items to a playlist:

Retrieve the multimedia content using the find() method of the ContentManager interface (in mobile and wearable applications):

var myPlaylist;

tizen.content.getPlaylists(function(playlists)
{
   myPlaylist = playlists[0];
   tizen.content.find(findSuccess, null, null, new tizen.AttributeFilter("type", "EXACTLY", "AUDIO"));
});

To add multiple items to the retrieved playlist, use the addBatch() method of the Playlist interface (in mobile and wearable applications):

function findSuccess(contents)
{
   if (contents.length >= 3)
   {
      myPlaylist.addBatch([contents[0], contents[1], contents[2]]);
   }
   else
   {
      console.log("Not enough items. Need at least 3");
   }
}

To add a single item to the retrieved playlist, use the add() method of the Playlist interface:

function findSuccess(contents)
{
   if (contents.length > 0)
   {
      myPlaylist.add(contents[0]);
   }
}

To retrieve items from a playlist, use the get() method of the Playlist interface:

function getSuccess(items)
{
   console.log("Playlist items:");
   for (var i = 0; i < items.length; ++i)
   {
      console.log("[" + i + "]: name:" + items[i].name);
   }
}

tizen.content.getPlaylists(function(playlists)
{
   var myPlaylist = playlists[0];
   myPlaylist.get(getSuccess);
});

To change the position of a single playlist item (track), use the move() method of the Playlist interface. The 2nd argument indicates how much and in which direction the item is moved.
Note that before moving the item, first you must retrieve it using the get() method.
```
var myItem; /* Assume that it was retrieved using the get() method */
function moveSuccess()
{
   console.log("move item SUCCESS");
}

tizen.content.getPlaylists(function(playlists)
{
   var myPlaylist = playlists[0];
   myPlaylist.move(myItem, -2, moveSuccess);
});
```
The example above moves the track 2 positions up on the playlist. The second argument of the move() method can be a negative value, which means moving the track up, or a positive value, which means moving the track down. If the value is greater than number of tracks above or below, the item is accordingly moved to the beginning or end of the playlist.
To change the order of all items in the playlist, use the setOrder() method. This feature is useful when sorting the playlist.
Following example reverses the order of the playlist items. For the setOrder() method to work, you must pass all items from the playlist. If an item is missing or an item from a different playlist is included, the InvalidValuesError exception is returned in the error callback.
1. Get all tracks using the get() method.
2. Within the success callback of the setOrder() method, create an array with the new order:
```
var items; /* Assume that it was retrieved using the get() method */
var newOrder = items.slice(0);
newOrder.reverse();
```
3. Execute the setOrder() method:
```
function setOrderSuccess()
{
   console.log("Set items order SUCCESS");
}

myPlaylist.setOrder(newOrder, setOrderSuccess); 
```