AllShare Tutorial for SDK 3.5

Published 2014-10-27 | (Compatible with SDK 3.5,4.5,5.0,5.1 and 2012,2013,2014 models)

This tutorial describes AllShare API usage and includes information about sample widget application.

Contents

Note

This tutorial is compatible with Samsung SDK 3.5 only. Please visit AllSHare Tutorial in order to see the tutorial written for SDK 4.5 version and higher.

Media providers: Device, MediaProviders, Device events
Media items: Item, ItemType, Folder, AudioItem, ImageItem, VideoItem
Browsing contents: Sample code for browseItems()
Searching contents: Sample code for searchItems()
Playing contents: Playing contents using HTML
Sample App: Sample App. How to run.
AllShare notes: Terminology and references

Media providers

Device

Device is parent class for each media provider. Application can get next information about Device: iconURL, unique Id, device name.

getIcon(): return string value of icon url
getID(): return string with uniq device id, not useful to user but needed to distinguish devices
getName(): return string, for DLNA devices it is friendly name from device description

Sample

var htmlStr = '',
    mediaProvider = providerArray[0],
    mediaProviderName = mediaProvider.getName(),
    mediaProviderIcon,
    mediaProviderID;

htmlStr += mediaProviderName + '<br />';

mediaProviderIcon = mediaProvider.getIcon();

if (mediaProviderIcon) {
    htmlStr += '<img src="' + mediaProviderIcon + '" /><br />';
}

mediaProviderID = mediaProvider.getID();
htmlStr += mediaProviderID;

MediaProvider

MediaProvider is child of Device. MediaProvider has next functions:

getMediaProviderType(): is used to distinguish different media providers, currently it is DLNA_MEDIA_SERVER
getRootFolder(): return object of root folder, needed for next browseItems()
browseItems(): return items of specified folder
searchItems(): searching items by argument string var

Sample

mediaProvider = providerArray[0];
if (mediaProvider.getMediaProviderType() == DLNA_MEDIA_SERVER) {
    alert("It is DLNA media server");
} else {
    alert("Local file system? Network file system? Ftp? What may be else?");
}

Device discovery

Application can ask for list of currently aviailable DMS devices using getMediaProviders().

Sample

var providerArray = serviceapis.mediasharing.mediaproviderfinder.getMediaProviders(),
    i = 0;

if (providerArray) {
    for (i = 0; i < providerArray.length; i++) {
        alert("providersName:" + providerArray[i].getName());
    }
}

Other way to access device, request it by known deviceID.

Sample

var deviceID, // this variable should have deviceID value of some device
    mediaProvider = serviceapis.mediasharing.mediaproviderfinder.getMediaProvider(deviceID);

Each DLNA device notify network when it appear or when it will disappear. CP may use this events to handle list of available devices. Application can set callback handler to obtain such events.

Sample

var providerDiscoveryCallback = {
    onmediaprovideradded : function (mediaProvider) {
        alert("new device appear : " + mediaProvider.getName());
        // adding new provider into providers list
    },
    onmediaproviderremoved : function (mediaProvider) {
      alert("device disappear : " + mediaProvider.getName());
      // removing provider from providers list
      // use getID() to distinguish removed device in device list
    }
}

serviceapis.mediasharing.mediaproviderfinder.setMediaProviderFinderCallback(providerDiscoveryCallback);

Media Items

Item

Item is parent type for any media items.

getTitle(): Get media item title (string format)
getDate(): Get creation date (string format)
getURI(): Get URL string pointing to contenst of this item
getType(): Get type of this item (ItemType format)

ItemType

ItemType included definition for next values:

ITEM_FOLDER: constant
ITEM_AUDIO: constant
ITEM_IMAGE: constant
ITEM_VIDEO: constant
ITEM_UNKNOWN: constant
value: keeps value of ItemType

To distinguish folder item use code below:

Sample

var itemType = item.getType();
if (itemType.item == itemType.ITEM_FOLDER) {
    // it is folder
}

FolderItem

FolderItem is child of Item.

isRootFolder(): return boolean value, let recognize root folder

AudioItem

AudioItem is child of Item

getAlbumArt(): return album art (image) url (string format)
getAlbumTitle(): get the album title
getArtist(): get artist of this contents
getDuration(): get duration of this audio in seconds (integer format)

ImageItem

ImageItem is child of Item

getThumbnail(): get image thumbnail url
getResolution(): get resolution (string format example: “1024x768”)
getLongitude(): get information about place
getLatitude(): get information about place

VideoItem

VideoItem is child of Item

getThumbnail(): get url on which the thumbnail of this item is located
getResolution(): resolution of this video (string format)
getDuration(): duration of this video in seconds (integer format)

Example: function printItem()

Next example shows how to access and print media item information.

Sample

function printItem(item) {
    if (item) {
        alert("title: " + item.getTitle());
        alert("date: " + item.getDate());
        alert("uri: " + item.getURI());

        var itemType = item.getType();
        if (itemType) {
            alert("ITEM_FOLDER: " + itemType.ITEM_FOLDER);
            alert("ITEM_AUDIO: " + itemType.ITEM_AUDIO);
            alert("ITEM_IMAGE: " + itemType.ITEM_IMAGE);
            alert("ITEM_VIDEO: " + itemType.ITEM_VIDEO);
            alert("ITEM_UNKNOWN: " + itemType.ITEM_UNKNOWN);

            switch(itemType.type) {
                case itemType.ITEM_FOLDER:
                    alert("ITEM_FOLDER");
                    alert("isRootFolder: " + item.isRootFolder());
                    break;

                case itemType.ITEM_AUDIO:
                    alert("ITEM_AUDIO");
                    alert("getAlbumArt: " + item.getAlbumArt());
                    alert("getAlbumTitle: " + item.getAlbumTitle());
                    alert("getArtist: " + item.getArtist());
                    alert("getDuration: " + item.getDuration());
                    break;

                case itemType.ITEM_IMAGE:
                    alert("ITEM_IMAGE");
                    alert("getThumbnail: " + item.getThumbnail());
                    alert("getResolution: " + item.getResolution());
                    alert("getLongitude: " + item.getLongitude());
                    alert("getLatitude: " + item.getLatitude());
                    break;

                case itemType.ITEM_VIDEO:
                    alert("ITEM_VIDEO");
                    alert("getThumbnail: " + item.getThumbnail());
                    alert("getResolution: " + item.getResolution());
                    alert("getDuration: " + item.getDuration());
                    break;

                case itemType.ITEM_UNKNOWN:
                    alert("ITEM_UNKNOWN");
                    break;

                default:
                    alert("unexpected value");
                    break;
            }
        } else {
            alert("item.getType() == null");
        }
    } else {
        alert("item == null");
    }
}

Browsing contents

Contents Navigation : using browseItems()

To navigate through contents structure similar to computers folders two function are defined in MediaProvider object:

getRootFolder(): return root of folder structure, type of result is FolderItem
browseItems(): it is asynchronous function, it obtain callback handlers for success and error cases

Sample

var browseHelper = {}; // helper object, what will implement browse functionality

browseHelper.resultItems = null; // this variable will keep finded items

 browseHelper.showFolderContents = function () { // this function executed when folder contents readed fully
     for (i = 0; i < resultItems.length; i++) {
         showMediaItemInfo(resultItems[i]);
    }
}


browseHelper.browseFolderInner = function (mediaProvider, folderItem) { // this function doing request for all items in folder

    var self = this;

    alert("browseHelper.browseFolder begin");

    // this function is callback, it called when items readed
    var browseItemsSuccessCallback = function (sc_itemList, sc_requestedStartIndex, sc_requestedFolderItem,
                                                sc_fEndOfItems, sc_mediaProvider) {
        alert("success callback");
        if (sc_itemList) {
            alert("itemsList.length : " + sc_itemList.length);
            alert("requestedStartIndex : " + sc_requestedStartIndex);
            alert("requestedFolderItem : " + sc_requestedFolderItem.getTitle());
            alert("fEndOfItems : " + sc_fEndOfItems);

            // copy result into 'resultItems'
            self.resultItems = self.resultItems.concat(sc_itemList);
            alert("add items into resultItems, new length :" + self.resultItems.length);

            // all items readed
            self.showFolderContents();
        }
    }

    // this function is callback, it called when error happend during items request
    var browseItemsErrorCallback = function (serviceAPIError, requestedProvider) {
        alert("serviceAPIError:" + serviceAPIError);
    }


    self.pendingOperation = null; // this variable will keep PendingOperation object, it can be used to cancel asynchronous request

    try {
        var startIndex = 0;
        // zero value means read all elements of folder
        var requestCount = 0;

        self.pendingOperation = mediaProvider.browseItems(browseItemsSuccessCallback, browseItemsErrorCallback,
                                                            folderItem, startIndex, requestCount);
    } catch(e) {
        alert("browseItems exception:" + e);
        self.pendingOperation = null;
    }
}


// this function browse 'folderItem' of 'mediaProvider'
browseHelper.browseFolder = function (mediaProvider, folderItem) {
     self = this;
     self.resultItems = [];
     self.browseFolderInner(mediaProvider, folderItem);
}


// calling part
var mediaProvider = providerArray[0]; // select first device from devices list
var folderItem = mediaProvider.getRootFolder();
browseHelper.browseFolder(mediaProvider, folderItem);

This code requesting all items located in folder.

The “search” is searching for items using keyword parameter. Searching is doing for whole contents of media provider. Usage is similar to browseItems(), it is asynchronous request. The function use callbacks to inform about success reading or error cases.

Sample

var searchHelper = {}; // helper object, what will implement search functionality


searchHelper.resultItems = null; // this variable will keep finded items


searchHelper.showFolderContents = function () {  // this function executed when folder contents readed fully
    for (i = 0; i < resultItems.length; i++) {
        showMediaItemInfo(resultItems[i]);
    }
}


searchHelper.searchItemsInner = function (mediaProvider, keyword) { // this function doing request for items

    var self = this;

    alert("searchHelper.searchItemsInner begin");

    // this function is callback, it called when next portion of items readed
    var searchItemsSuccessCallback = function (sc_itemList, sc_requestedStartIndex, sc_keyword, sc_fEndOfItems, sc_mediaProvider) {
        alert("success callback");
        if (sc_itemList) {
            alert("itemsList.length : " + sc_itemList.length);
            alert("requestedStartIndex : " + sc_requestedStartIndex);
            alert("keyword : " + sc_keyword);
            alert("fEndOfItems : " + sc_fEndOfItems);

            // copy result into 'resultItems' and request for another portion if needed
            self.resultItems = self.resultItems.concat(sc_itemList);
            alert("add items into resultItems, new length :" + self.resultItems.length);

            // all items readed
            self.showFolderContents();
        }
    }

    // this function is callback, it called when error happend during items request
    var searchItemsErrorCallback = function (serviceAPIError, requestedProvider) {
        alert("serviceAPIError:" + serviceAPIError);
    }


    self.pendingOperation = null; // this variable will keep PendingOperation object, it can be used to cancel asynchronous request

    try {
        var startIndex = 0;
        // zero value means read all elements of result
        var requestCount = 0;

        self.pendingOperation = mediaProvider.searchItems(searchItemsSuccessCallback, searchItemsErrorCallback,
                                                            keyword, startIndex, requestCount);
    } catch (e) {
        alert("searchItems exception: " + e);
        self.pendingOperation = null;
    }
}


// this function search items by "keyword" in "mediaProvider"
searchHelper.search = function (mediaProvider, keyword) {
    self = this;
    self.resultItems = [];
    self.searchItemsInner(mediaProvider, keyword);
}


// calling part
var mediaProvider = providerArray[0]; // select first device from devices list
searchHelper.searchFolder(mediaProvider, "Jackson");

Playing contents

Contents playing

Application can access contents of media items through contents URL. For next examples, next html code used:

<html>
  <body>
    <div id="div_id_item">Item viewer</div>
  </body>
</html>

Samsung TV browser included support for html5. Video and Audio playing will use <video> and <audio> tags of html5.

Displaying images

Browser has embedded support for displaying images.

Sample

function showImageViewer (url) {

    var viewerHtml = "<table border=1><tr><td>";
    var url = self.currentItem.getURI();

    if (url) {
        viewerHtml += "<img src=" + url + " height=400 width=600>";
    }

    viewerHtml += "</td></tr></table>";
    var element = document.getElementById("div_id_item");

    if (element) {
        element.innerHTML = viewerHtml;
    }
}

Playing audio

Tag <audio> can be used for audio playing.

Sample

function showAudioPlayer (url) {

    var viewerHtml = "";
    var playerId = "playerId";
    var url = self.currentItem.getURI();

    if (url) {
        viewerHtml += "URL : " + url + "<br>";
        viewerHtml += "<audio id=\"" + playerId + "\" src=\"";
        viewerHtml += url + "\" controls=\"controls\"> Browser does not support the audio tag</audio>";
    }

    var element = document.getElementById("div_id_item");

    if (element) {
        element.innerHTML = viewerHtml;
    }
}

Playing video

AVPlay API can be used for video playing.

Code example

function showImage(url) {
    var playerId = PLAYER_ID;
    var videourl = self.currentItem.getURI();


    var playSuccessCB = {
        console.log("playing the video is successfully.");
    };

    function successCB(avplayObj) {
        avplayObj.init();
        avplayObj.open(videourl);
        avplayObj.play(
            playSuccessCB,
            function (error) {
                console.error(error.message);
            },
            5
        );
    }

    function errorCB(error) {
        console.log("Cannot get avplay object : " + error.name);
    }

    try {
        webapis.avplay.getAVPlay(successCB, errorCB);
    } catch (error) {
        console.log(error.name);
    }
}

Sample App

Downloading link

Note

The files needed for the sample application are: here.

This is screen shot of Sample App, in contents browsing mode:

Figure 1. Sample app screenshot.

Portions of this page are reproduced from work created and shared by the Android Open Source Project
and used according to terms described in the Creative Commons 2.5 Attribution License.

Smart TV

AllShare Tutorial for SDK 3.5

Media providers

Device

MediaProvider

Device discovery

Media Items

Item

ItemType

FolderItem

AudioItem

ImageItem

VideoItem

Example: function printItem()

Browsing contents

Contents Navigation : using browseItems()

Searching contents

Searching Contents : using searchItems()

Playing contents

Contents playing

Displaying images

Playing audio

Playing video

Sample App

Downloading link