Samsung Electronics logo

Samsung Web API: ImageViewer


Introduction

This API allows developers to display images and control the image viewer.

It provides MRCP (Media Renderer Control Point) features for control of the image files playing on a remote Digital Living Network Alliances (DLNA) device that supports Digital Media Renderer (DMR), which is described in the DLNA specification.


Table of Contents


Summary of Interfaces and Methods

Interface Method
ImageViewerSuccessCallback void onsuccess(DeviceId viewerId)
ImageViewerErrorCallback void onerror(WebAPIError error, DeviceId viewerId)
ImageViewerStateChangedCallback void onstatechange(ImageViewerState state, DeviceId viewerId)
ImageViewerStateCallback void onsuccess(ImageViewerState state, DeviceId viewerId)
ImageViewer ViewController getViewController()
void show(Item item, ImageViewerSuccessCallback successCallback, ImageViewerErrorCallback? errorCallback)
void hide(ImageViewerSuccessCallback successCallback, ImageViewerErrorCallback? errorCallback)
void getState(ImageViewerStateCallback successCallback, ImageViewerErrorCallback? errorCallback)
long addImageViewerStateChangeListener(ImageViewerStateChangedCallback stateCallback)
void removeImageViewerStateChangeListener(long changeListenerId)

1. Type Definitions

1.1. ImageViewerState

Specifies the state of a image viewer.

    enum ImageViewerState { 
                         "UNKNOWN",
                         "STOPPED", 
                         "BUFFERING", 
                         "SHOWING", 
                         "CONTENT_CHANGED"
    };
  • UNKNOWN: The imageviewer is in an unknown state.
  • STOPPED: The imageviewer is in the stopped state.
  • BUFFERING: The imageviewer is in the buffering state.
  • SHOWING: The imageviewer is in the showing state.
  • CONTENT_CHANGED: The imageviewer is in the content changed state.

2. Interfaces

2.1. ImageViewerSuccessCallback

Generic success callback for image viewer related operations.

    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerSuccessCallback {
        
        void onsuccess(DeviceId viewerId);
    };

METHODS

onsuccess

Callback function invoked when operation is completed successfully.

Signature
void onsuccess(DeviceId viewerId);
Parameters
  • viewerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the imageviewer device which made a the request.

2.2. ImageViewerErrorCallback

Generic error callback for image viewer related operations.

    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerErrorCallback {
        
        void onerror(WebAPIError error,
                     DeviceId viewerId);
    };

METHODS

onerror

Callback function invoked when error occurs.

Signature
void onerror(WebAPIError error, DeviceId viewerId);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: WebAPIError object which indicates error type and message.
  • viewerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the ImageViewer device which made the request.

2.3. ImageViewerStateChangedCallback

Callback invoked when the state of the image viewer changed.

    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerStateChangedCallback {
        
         void onstatechange(ImageViewerState state,
                            DeviceId viewerId);
    };

METHODS

onstatechange

Callback function invoked when the state changed.

Signature
void onstatechange(ImageViewerState state, DeviceId viewerId);
Parameters
  • state
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerState.
    • Description: The state of image viewer.
  • viewerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of imageviewer device.

2.4. ImageViewerStateCallback

Callback invoked when state was obtained successfully.

    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerStateCallback {
        
         void onsuccess(ImageViewerState state,
                        DeviceId viewerId);
    };

METHODS

onsuccess

Callback invoked when the operation is completed successfully.

Signature
void onsuccess(ImageViewerState state, DeviceId viewerId);
Parameters
  • state
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerState.
    • Description: The state of image viewer.
  • viewerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of imageviewer device.

2.5. ImageViewer

Interface provides a means of controlling an image viewer device.

    [NonInterfaceObject] interface ImageViewer : DeviceDevice {
        
        ViewController getViewController();
        
        void show(Item item,
                  ImageViewerSuccessCallback successCallback, 
                  optional ImageViewerErrorCallback? errorCallback);
        
        void hide(ImageViewerSuccessCallback successCallback,
                  optional ImageViewerErrorCallback? errorCallback);
        
        void getState(ImageViewerStateCallback successCallback,
                      optional ImageViewerErrorCallback? errorCallback);
        
        long addImageViewerStateChangeListener(ImageViewerStateChangedCallback stateCallback);
        
        void removeImageViewerStateChangeListener(long changeListenerId);
    
    };

"ImageViewer" is a specific type of device. Developer can obtain the object by using method that retrieves devices.

Code example
 
 var serviceProvider; // it is assumed that you obtained serviceProvider. For further details, see creatServiceProvider(..).
 var deviceId;           // it is assumed that an imageviewer's device ID has already been determined.
 
 try {
     var imageviewer = serviceProvider.getDeviceFinder().getDevice("IMAGEVIEWER", deviceId);

     // Display out the device's name
     console.log(imageviewer.name);
     
 } catch(e) {
      console.log(e.name);
 }
 
 

METHODS

getViewController

Obtain the object of ViewController.

Signature
ViewController getViewController();

Some ImageViewers may not have a ViewController, which case the return value should be null If any error occurs, WebAPIException will be thrown.

Return value
ViewController The object of ViewController.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

show

Show image content to the player with the item and contentInfo.

Signature
void show(Item item, ImageViewerSuccessCallback successCallback, optional ImageViewerErrorCallback? errorCallback);

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • NotFoundError: if the item does not exist.
  • InvalidValuesError: if any of the input parameters contains an invalid value.
  • InvalidStateError: if the device or state is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • TimeOutError: If the request is times out.
  • UnknownError: In the case of any other error.
Parameters
  • item
    • Optional: No.
    • Nullable: No.
    • Type: Item.
    • Description: An image item to be showed.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerSuccessCallback.
    • Description: Success callback invoked when the operation is completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ImageViewerErrorCallback.
    • Description: Error callback invoked when error occurs.
Exceptions
  • WebAPIException:

    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 any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var imageviewer; // it is assumed that you have obtained an imageviewer object.
 var url; // this is assumed to be the URL of a web image content;
 var image = new Item(url); // identifies item to be shown.

 //Define success callback
 function imgViewerSCB(viewerId){
         console.log("Image Viewer Device ID: " + viewerId);
 }
 
 //Define error callback
 function imgViewerECB(error, viewerId){
         console.log(error.message);
 }
 
 //Retrieve the device. See sample code in devicediscovery module. Here we assume that we already have the object named "imgViewerDev".
 try {
         imageviewer.show(image, imgViewerSCB, imgViewerECB);
 } catch(e) {
         console.log(e.message);
 }
 
 

hide

Hide the image displayed in the image viewer.

Signature
void hide(ImageViewerSuccessCallback successCallback, optional ImageViewerErrorCallback? errorCallback);

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • InvalidStateError: if the device or state is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • TimeOutError: If the request times out.
  • UnknownError: In the case of any other error.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerSuccessCallback.
    • Description: Success callback invoked when the operation is completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ImageViewerErrorCallback.
    • Description: Error callback invoked when error occurs.
Exceptions
  • WebAPIException:

    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 any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var imageviewer; // it is assumed that you obtained an imageviewer object.

 // Define success callback
 function imgViewerSCB(viewerId){
         console.log("Image Viewer Device ID: " + viewerId);
 }
 
 // Define error callback
 function imgViewerECB(error, viewerId){
         console.log(error.message);
 }
 
 try{
         imageviewer.hide(imgViewerSCB, imgViewerECB);
 }catch(e){
         console.log(e.message);
 }

 

getState

Retrieve the state of the image viewer.

Signature
void getState(ImageViewerStateCallback successCallback, optional ImageViewerErrorCallback? errorCallback);

The error callback is launched with these error types:

  • InvalidStateError: if the device or state is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • TimeOutError: If the request times out.
  • UnknownError: In the case of any other error.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerStateCallback.
    • Description: Success callback invoked when the operation has completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ImageViewerErrorCallback.
    • Description: Error callback invoked when error occurs.
Exceptions
  • WebAPIException:

    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 any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var imageviewer; // it is assumed that you obtained an imageviewer object.

 //Define success callback
 function imgViewerStateSCB(state, viewerId) {
         console.log(state);
 }
 
 //Define error callback
 function imgViewerStateECB(error, viewerId) {
         console.log(error.message);
 }

 try {
         imageviewer.getState(imgViewerStateSCB, imgViewerStateECB);
 } catch(e) {
         console.log(e.message);
 }
 
 

addImageViewerStateChangeListener

Set the image viewer event listener.

Signature
long addImageViewerStateChangeListener(ImageViewerStateChangedCallback stateCallback);
Parameters
  • stateCallback
    • Optional: No.
    • Nullable: No.
    • Type: ImageViewerStateChangedCallback.
    • Description: Callback interface that will capture the event.
Return value
long Identifier for the event listener. It can be used to remove the listener.
Exceptions
  • WebAPIException:

    with error type UnknownError, In any other error case.

    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 any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var imageviewer; // it is assumed that you obtained an imageviewer object.

 //Define state change callback
 function imgViewerStateChangeCB(state, viewerId) {
         console.log("Current State: " + state);
 }
 
 try {
     imageviewer.addImageViewerStateChangeListener(imgViewerStateChangeCB);
 } catch (e) {
     console.log(e.message);
 }
 
 

removeImageViewerStateChangeListener

Remove the event listener.

Signature
void removeImageViewerStateChangeListener(long changeListenerId);
Parameters
  • changeListenerId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: ID of the event listener returned by addViewControllerEventListener.
Exceptions
  • WebAPIException:

    with error type UnknownError, any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var imageviewer; // it is assumed that you have obtained an imageviewer object.
  var handle; // it is assumed that addImageViewerStateChangeListener() has already been invoked.

 //Define state change callback
 function imgViewerStateChangeCB(state, viewer){
         console.log("Current State: " + state);
 }
 
 try {
     imageviewer.removeImageViewerStateChangeListener(handle);
 } catch (e) {
     console.log(e.message);
 }
 
 

3. Full WebIDL

module ImageViewer {

    enum ImageViewerState { 
                         "UNKNOWN",
                         "STOPPED", 
                         "BUFFERING", 
                         "SHOWING", 
                         "CONTENT_CHANGED"
    }; 
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerSuccessCallback {
        
        void onsuccess(DeviceId viewerId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerErrorCallback {
        
        void onerror(WebAPIError error,
                     DeviceId viewerId);
    };    
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerStateChangedCallback {
        
         void onstatechange(ImageViewerState state,
                            DeviceId viewerId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ImageViewerStateCallback {
        
         void onsuccess(ImageViewerState state,
                        DeviceId viewerId);
    };
    
    [NonInterfaceObject] interface ImageViewer : DeviceDevice {
        
        ViewController getViewController();
        
        void show(Item item,
                  ImageViewerSuccessCallback successCallback, 
                  optional ImageViewerErrorCallback? errorCallback);
        
        void hide(ImageViewerSuccessCallback successCallback,
                  optional ImageViewerErrorCallback? errorCallback);
        
        void getState(ImageViewerStateCallback successCallback,
                      optional ImageViewerErrorCallback? errorCallback);
        
        long addImageViewerStateChangeListener(ImageViewerStateChangedCallback stateCallback);
        
        void removeImageViewerStateChangeListener(long changeListenerId);
    
    };
      
};