AllSHare Tutorial for SDK 4.5
This tutorial describes AllShare API usage and includes information about sample widget application working under Samsung SDK 4.5 and 2013 devices.
Note
This tutorial is compatible with Samsung SDK 4.5. If you are using an earlier version, see the AllShare Tutorial for SDK 3.5.
Media providers
MediaProvider
Application can get information about MediaProvider using next attributes:
- id
- is string with uniq device id, for DLNA devices it is UDN from device description
- deviceDomain
- is string value of device domain
- deviceType
- is string value of deviceType e.g. “MEDIAPROVIDER”
- iconArray
- array of icons info objects
- ipAddress
- media providers IP address
- modelName
- media providers model name
- name
- media providers name, for DLNA devices it is friendly name from device description
- isSearchable
- boolean flag, true value if media provider supporting Searching
- rootFolder
- root folder item, is used for browsing
IconArray
IconArray object has next attributes:
- depth
- icons bits per pixel
- height
- icons heigth in pixels
- width
- icons width in pixels
- mimeType
- icon file mimetype, DOMString
- iconUri
- icon URL, DOMString
Device discovery
To access get MediaProviders list. Application needs to do next calls.
- Create ServiceProvider
- Get ServiceProvider object
- Get DeviceFinder object from ServiceProvider
- Set device discoveryListener to DeviceFinder object. To obtain appear or disappear events.
- Access devices list using getDeviceList()
Code example
function serviceProviderCreateSuccessCallback(serviceProvider) {
alert("serviceProviderCreateSuccessCallback()");
}
function serviceProviderErrorCallback(error, state) {
alert("serviceProviderErrorCallback() error.name: " + error.name + " error.message:" +error.message + " state:" + state);
}
try {
// need to create ServiceProvider first
window.webapis.allshare.serviceconnector.createServiceProvider(serviceProviderCreateSuccessCallback, serviceProviderErrorCallback);
} catch(e) {
// e. WebAPIException
alert(" exception : " + e.name + "(" + e.code + ") :" + e.message);
}
function showMediaProviderInfo(mediaProvider) {
alert("mediaProvider.name:" + mediaProvider.name);
alert("mediaProvider.id:" + mediaProvider.id);
alert("mediaProvider.ipAddress:" + mediaProvider.ipAddress);
for (var iconIdx = 0; iconIdx < mediaProvider.iconArray.length; iconIdx++) {
alert("icon.iconUri:" + mediaProvider.iconArray[iconIdx].iconUri);
}
}
var serviceProvider = window.webapis.allshare.serviceconnector.getServiceProvider();
if (serviceProvider) {
var deviceFinder = serviceProvider.getDeviceFinder();
if (deviceFinder) {
var deviceDiscoveryCallback = {
ondeviceadded : function (d) {
alert("ondeviceadded: " + d.name);
showMediaProviderInfo(d);
},
ondeviceremoved : function (d) {
alert("ondeviceremoved: " + d.name);
}
};
var listenerId = deviceFinder.addDeviceDiscoveryListener(deviceDiscoveryCallback);
var deviceType = "MEDIAPROVIDER";
var mediaProvidersArray = deviceFinder.getDeviceList(deviceType);
for (var i = 0; i < mediaProvidersArray.length; i++) {
var mediaProvider = mediaProvidersArray[i];
showMediaProviderInfo(mediaProvider);
}
}
}
Media Items
Item
Item object keeps information about any media items: folders, audio, video, images. Item has next attributes:
- itemType
- Get item type. Type DOMString. Possible values : “FOLDER”, “AUDIO”, “VIDEO”, “IMAGE”, “UNKNOWN”.
- title
- Item title. DOMString format.
- fileSize
- fileSize in bytes. Numeric value.
- itemUri
- URL pointing to contenst of this item. DOMString format.
- mimeType
- mimeType of item. DOMString format.
- thumbnailUri
- URL pointing contents thumbnail. DOMString format.
- duration
- for audio/video it is media duration in seconds. Numeric format.
- date
- media creation date. Date object format.
- albumTitle
- Album title. DOMString format.
- artist
- Artist name. DOMString format.
- genre
- Genre. DOMString format.
- width
- Contents width for video/images. Numeric format.
- height
- Contents height for video/images. Numeric format.
- extension
- For media items it included file extension. DOMString format.
- subtitleUri
- URI of subtitles for video items. DOMString format.
- isRootFolder
- Boolean format.
To distinguish folder item use next:
Code example
var itemType = item.itemType;
if (itemType == "FOLDER") {
// it is folder
}
Example: function printItem()
Next example shows how to access and print media item information.
Code example
function printItem(item) {
if (item) {
alert(" albumTitle: " + item.albumTitle);
alert(" artist: " + item.artist);
alert(" date: " + item.date);
alert(" duration: " + item.duration);
alert(" extension: " + item.extension);
alert(" fileSize: " + item.fileSize);
alert(" genre: " + item.genre);
alert(" location: " + item.location);
alert(" mimeType: " + item.mimeType);
alert(" width: " + item.width);
alert(" height: " + item.height);
alert(" subtitleUri: " + item.subtitleUri);
alert(" thumbnailUri: " + item.thumbnailUri);
alert(" title: " + item.title);
alert(" itemType: " + item.itemType);
alert(" itemUri: " + item.itemUri);
alert(" isRootFolder: " + item.isRootFolder);
alert(" contentBuildType: " + item.contentBuildType);
} else {
alert("item == null");
}
}
Searching contents
Searching Contents: using search()
The search is searching for items using keyword parameter. Searching is doing for whole contents of media provider. Usage is similar to browse(), it is asynchronous request. The function use callbacks to inform about success reading or error cases.
Code example
var searchHelper = {}; // helper object, what will implement search functionality
searchHelper.resultItems = []; // 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.search = function (mediaProvider, keyword) { // this function doing request for items
var self = this;
// this function is callback, it called when next portion of items readed
var mediaProviderSuccessCallback = function (sc_itemList, sc_fEndOfItems, sc_providerId) {
alert("success callback");
alert("itemsList.length : " + sc_itemList.length);
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 mediaProviderErrorCallback = function (webAPIError, providerId) {
alert("webAPIError:" + webAPIError.name + "/" + webAPIError.message);
}
var startIndex = 0;
// zero value means read all elements of result
var requestCount = 0;
self.resultItems = [];
try {
mediaProvider.search(keyword, startIndex, requestCount, mediaProviderSuccessCallback, mediaProviderErrorCallback);
} catch(e) {
alert("searchItems exception: " + e.name + "/" + e.message);
}
}
// calling part
var mediaProvider = ???; // select first device from devices list
searchHelper.search(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.
Code example
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.
Code example
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);
}
}
Notes
Terminology & Acronyms
UPnP | Universal Plug and Play |
DLNA | Digital Living Network Alliance |
DMR | Device Media Renderer |
CP | Control Point |
DMS | Device Media Server |
References
- Samsung API Specification
- UPnP forum: http://www.upnp.org
- UPnP device architecture Version 1.0
- UPnP AV Architecture:0.83 For Universal Plug and Play Version 1.0
- ContentDirectory:1 Service Template Version 1.01
- DLNA Alliance: http://www.dlna.org
- DLNA Guidelines August 2009, Volume 1: Architectures and Protocols
- DLNA Guidelines August 2009, Volume 2: Media Format Profiles