Samsung Electronics logo

Samsung Web API: WebAPIs


Introduction

This API provides the basic definitions that are used in all other Web APIs (Generic purpose Web APIs).

These include generic callbacks for error, the WebAPIError interface and object filters. Additionally, this API also specifies the location in the ECMAScript hierarchy in which the Web APIs are instantiated (window.webapis).

For more information on the WebAPIs features, see WebAPIs Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
WindowWebAPIs
WebAPIs
AbstractFilter
AttributeFilter
AttributeRangeFilter
CompositeFilter
SortMode
SimpleCoordinates
WebAPIException
WebAPIError
SuccessCallback void onsuccess()
ErrorCallback void onerror(WebAPIError error)

1. Type Definitions

1.1. FilterMatchFlag

Filter match flag.

  enum FilterMatchFlag { "EXACTLY", "FULLSTRING", "CONTAINS", "STARTSWITH", "ENDSWITH", "EXISTS" };

These values are supported:

  • EXACTLY - Indicates that an attribute value should match exactly with the specified default value. For strings, this type of comparison is case-sensitive.
  • FULLSTRING - Indicates String-based comparison and that the attribute value should match the whole string (case insensitive).
  • CONTAINS - Indicates that an attribute value should contain the specified string. This type of comparison works only on strings and is case insensitive.
  • STARTSWITH - Indicates that an attribute value should start with the specified string. This type of comparison works only on strings and is case insensitive.
  • ENDSWITH - Indicates that an attribute value should end with the specified string. This type of comparison works only on strings and is case insensitive.
  • EXISTS - Indicates that a filter comparison should match if the specified attribute exists.

1.2. SortModeOrder

An enumerator that indicates the sorting order.

  enum SortModeOrder { "ASC", "DESC" };

The following values are supported:

  • "ASC" - Indicates the sorting order is ascending
  • "DESC" - Indicates the sorting order is descending

1.3. CompositeFilterType

An enumerator that indicates the type of composite filter.

  enum CompositeFilterType { "UNION", "INTERSECTION" };

The following values are supported:

  • UNION - Indicates that the composite is a union of filters ("OR" operator)
  • INTERSECTION - Indicates that the composite is an intersection of filters ("AND" operator)

1.4. StringArray

Array of DOMStrings.

  typedef sequence<DOMString> StringArray;

1.5. UnsignedShortArray

Array of unsigned short values.

  typedef sequence<unsigned short> UnsignedShortArray;

1.6. ShortArray

Array of short values.

  typedef sequence<short> ShortArray;

2. Interfaces

2.1. WindowWebAPIs

Defines the webapis interface as part of the window global object.

  [NoInterfaceObject] interface WindowWebAPIs {
    readonly attribute WebAPIs webapis;
  };
  Window implements WindowWebAPIs;

There will be a window.webapis object that allows accessing the functionality of the webapis API.

2.2. WebAPIs

The Samsung Web API's root. The WebAPIs interface will be always available within the Window object in the ECMAScript hierarchy.

  [NoInterfaceObject] interface WebAPIs {

  };

2.3. AbstractFilter

This is a common interface used by different types of object filters.

  [NoInterfaceObject] interface AbstractFilter {
  };

Never use this base interface directly, instead use AbstractFilter subtypes, such as AttributeFilter, AttributeRangeFilter, and CompositeFilter.

2.4. AttributeFilter

This interface represents a set of filter.

  [Constructor(DOMString attributeName, optional FilterMatchFlag? matchFlag, optional any matchValue)]

  interface AttributeFilter : AbstractFilter {


    attribute DOMString attributeName;

    attribute FilterMatchFlag matchFlag;


    attribute any matchValue;
  };

It represents the query statement for the specified value of the matchValue by the rule of matchFlag.

If no matchValue is defined, the filter will match all objects that have the attribute defined (same as the "EXISTS" filter works), otherwise, it will only match objects which have an attribute that matches the specified value.

Code example
 // Define success callback
 function successCallback(contacts) {
   console.log(contacts.length + " contacts found.");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("An error occurred: " + error.message);
 }

 // Create an attribute filter based on first name: "First name should contain 'Chris' (case insensitive)"
 var filter = new webapis.AttributeFilter("name.firstName", "CONTAINS", "Chris");
 // Send request on contact address book.
 webapis.contact.getDefaultAddressBook().find(successCallback, errorCallback, filter);
 

ATTRIBUTES

DOMString attributeName

The name of the object attribute used for filtering.

This is the name of the object attribute exactly as it is defined in the object's interface. For attributes of complex type, use fully-qualified names (such as 'organizations.role' to filter on a contact's role in an organization).

For attributes of an array type, the filter will match if any value in the array matches.

FilterMatchFlag matchFlag

The match flag used for attribute-based filtering.

By default, this attribute is set to "EXACTLY".

any matchValue

The value used for matching.

The filter will match if the attribute value matches the given matchValue.

This value is not used if the matchFlag is set to "EXISTS". By default, this attribute is set to null.

2.5. AttributeRangeFilter

AttributeRangeFilter represents a filter based on an object attribute which has values that are within a particular range.

  [Constructor(DOMString attributeName, optional any initialValue, optional any endValue)]

  interface AttributeRangeFilter : AbstractFilter {

    attribute DOMString attributeName;


    attribute any initialValue;


    attribute any endValue;
  };

Range filters, where only one boundary is set, are available.

Code example
 // Define success callback
 function successCallback(events) {
   console.log(events.length + " events today.");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("An error occurred: " + error.message);
 }
 
 // Create an attribute range filter based on event start date: "All events occurring today".
 var now_dt = webapis.time.getCurrentDateTime();
 var today_begin = new webapis.TZDate(now_dt.getFullYear(), now_dt.getMonth(), now_dt.getDate());
 var today_end = today_begin.addDuration(new webapis.TimeDuration(1, "DAYS"));
 var filter = new webapis.AttributeRangeFilter("startDate", today_begin, today_end);
 
 // Send a search request to default event calendar.
 webapis.calendar.getDefaultCalendar("EVENT").find(successCallback, errorCallback, filter);
 

ATTRIBUTES

DOMString attributeName

The name of the object attribute used for filtering.

The value of this attribute is exactly as it is defined in the object's interface. For attributes of complex type, use fully-qualified names (such as 'organizations.role' to filter on a contact's role in an organization).

For attributes of array type, the filter will match if any value in the array matches.

any initialValue

Objects with an attribute that is greater than or equal to initialValue will match.

By default, this attribute is set to null.

any endValue

Objects with an attribute that is strictly lower than to endValue will match.

By default, this attribute is set to null.

2.6. CompositeFilter

CompositeFilter represents a set of filters.

  [Constructor(CompositeFilterType type, optional AbstractFilter[]? filters)]

  interface CompositeFilter : AbstractFilter {


    attribute CompositeFilterType type;
    

    attribute AbstractFilter[] filters;
  };

The composite filters can be one of the 2 types:

  • The union - used to filter objects that match any of the filters it includes.
  • The intersection - used to filter objects that match all filters it includes.
Code example
 // Define success callback
 function successCallback(contacts) {
   console.log(contacts.length + " contacts found.");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("An error occurred: " + error.message);
 }

 // Create an attribute filter based on first name: "First name should contain 'Chris' (case insensitive)
 var firstNameFilter = new webapis.AttributeFilter("name.firstName", "CONTAINS", "Chris");

 // Create an attribute filter based on last name: "Last name should be exactly 'Smith' (case insensitive)
 var lastNameFilter = new webapis.AttributeFilter("name.lastName", "EXACTLY", "Smith"};

 // Create a filter based on the intersection of these two filter:
 // "First name should contain 'Chris' AND last name should be 'Smith'".
 var filter = new webapis.CompositeFilter("INTERSECTION", [firstNameFilter, lastNameFilter]);

 // Send request on contact address book.
 webapis.contact.getDefaultAddressBook().find(successCallback, errorCallback, filter);
 

ATTRIBUTES

CompositeFilterType type

Composite filter type.

AbstractFilter[] filters

The list of filters in the composite filter.

2.7. SortMode

SortMode is a common interface used for sorting of queried data.

 [Constructor(DOMString attributeName, optional SortModeOrder? order)] 

  interface SortMode {

    attribute DOMString attributeName;    


    attribute SortModeOrder order setraises(WebAPIException);
  };

Note that the sorting result of list type attributes is not determined.

Code example
 // Define a success callback
 function successCallback(contacts) {
   // The returned contacts are sorted by first name (ascending)
   console.log(contacts.length + " contacts found.");
 }

 // Define an error callback
 function errorCallback(error) {
   console.log("An error occurred: " + error.message);
 }
 
 // Create an attribute filter based on first name: "First name should contain 'Chris' (case insensitive)"
 var filter = new webapis.AttributeFilter("name.firstName", "CONTAINS", "Chris");
 // Sort by first name, ascending
 var sortMode = new webapis.SortMode("name.firstName", "ASC");
 // Send request on contact address book.
 webapis.contact.getDefaultAddressBook().find(successCallback, errorCallback, filter, sortMode);
 

ATTRIBUTES

DOMString attributeName

The name of the object attribute used for sorting.

SortModeOrder order

The type of the sorting.

By default, this attribute is set to ASC.

2.8. SimpleCoordinates

SimpleCoordinates represents a point (latitude and longitude) in map coordinate system.

[Constructor(double latitude, double longitude)]  

  interface SimpleCoordinates {


    attribute double latitude setraises(WebAPIException);


    attribute double longitude setraises(WebAPIException);
  };

Latitude and longitude are of the WGS84 datum.

ATTRIBUTES

double latitude

Latitude.

double longitude

Longitude.

2.9. WebAPIException

Generic exception interface.

    interface WebAPIException {


        readonly attribute unsigned short code;


        readonly attribute DOMString name; 
            

        readonly attribute DOMString message;
                   

        const unsigned short INDEX_SIZE_ERR = 1; 
        

        const unsigned short DOMSTRING_SIZE_ERR = 2; 
        

        const unsigned short HIERARCHY_REQUEST_ERR = 3; 
        

        const unsigned short WRONG_DOCUMENT_ERR = 4; 


        const unsigned short INVALID_CHARACTER_ERR = 5;


        const unsigned short NO_DATA_ALLOWED_ERR = 6; 


        const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7; 


        const unsigned short NOT_FOUND_ERR = 8; 


        const unsigned short NOT_SUPPORTED_ERR = 9; 


        const unsigned short INUSE_ATTRIBUTE_ERR = 10; 


        const unsigned short INVALID_STATE_ERR = 11; 


        const unsigned short SYNTAX_ERR = 12; 


        const unsigned short INVALID_MODIFICATION_ERR = 13; 


        const unsigned short NAMESPACE_ERR = 14; 


        const unsigned short INVALID_ACCESS_ERR = 15; 


        const unsigned short VALIDATION_ERR = 16; 
 

        const unsigned short TYPE_MISMATCH_ERR = 17; 
 

        const unsigned short SECURITY_ERR = 18; 
 

        const unsigned short NETWORK_ERR = 19; 
 

        const unsigned short ABORT_ERR = 20; 


        const unsigned short URL_MISMATCH_ERR = 21; 
 

        const unsigned short QUOTA_EXCEEDED_ERR = 22; 
 

        const unsigned short TIMEOUT_ERR = 23; 
 

        const unsigned short INVALID_NODE_TYPE_ERR = 24; 


        const unsigned short DATA_CLONE_ERR = 25; 
  };

This interface will be used by the APIs to throw errors synchronously.

The attempt to set an attribute value may or may not raise WebAPIException synchronously with error type TypeMismatchError or InvalidValuesError.

Code example
 try {
     webapis.contact.getDefaultAddressBook().find();
 } catch (ex) {
     // The value of ex parameter is a WebAPIException object.
    if (ex.code == webapis.WebAPIException.NOT_SUPPORTED_ERR) {
        // find() API is not supported in some platform
    } else if (ex.code == webapis.WebAPIException.TYPE_MISMATCH_ERR)
       // find() API throws "TypeMismatchError"
    }
 } 
 

CONSTANTS

unsigned short INDEX_SIZE_ERR

The index is not in the allowed range.

unsigned short DOMSTRING_SIZE_ERR

The specified range of text is too large.

unsigned short HIERARCHY_REQUEST_ERR

The operation would yield an incorrect node tree.

unsigned short WRONG_DOCUMENT_ERR

The object is in the wrong document.

unsigned short INVALID_CHARACTER_ERR

The string contains invalid characters.

unsigned short NO_DATA_ALLOWED_ERR

If data is specified for a Node which does not support data.

unsigned short NO_MODIFICATION_ALLOWED_ERR

If an attempt is made to modify an object where modifications are not allowed.

unsigned short NOT_FOUND_ERR

If an attempt is made to reference a Node in a context where it does not exist.

unsigned short NOT_SUPPORTED_ERR

If the implementation does not support the requested type of object or operation.

unsigned short INUSE_ATTRIBUTE_ERR

If an attempt is made to add an attribute that is already in use elsewhere.

unsigned short INVALID_STATE_ERR

If an attempt is made to use an object that is not, or is no longer, usable.

unsigned short SYNTAX_ERR

If an invalid or illegal string is specified.

unsigned short INVALID_MODIFICATION_ERR

If an attempt is made to modify the type of the underlying object.

unsigned short NAMESPACE_ERR

If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.

unsigned short INVALID_ACCESS_ERR

If a parameter or an operation is not supported by the underlying object.

unsigned short VALIDATION_ERR

If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done. This code is used in [DOM Level 3 Validation].

unsigned short TYPE_MISMATCH_ERR

If the type of an object is incompatible with the expected type of the parameter associated to the object.

unsigned short SECURITY_ERR

If an attempt is made to perform an operation or access some data in a way that would be a security risk or a violation of the user agent's security policy.

unsigned short NETWORK_ERR

If a network error occurs in synchronous requests.

unsigned short ABORT_ERR

If the abort error occurs in asynchronous requests by user prompt.

unsigned short URL_MISMATCH_ERR

If the given URL does not match another URL

unsigned short QUOTA_EXCEEDED_ERR

If the quota has been exceeded..

unsigned short TIMEOUT_ERR

If the operation could not be completed because it timed out.

unsigned short INVALID_NODE_TYPE_ERR

If the supplied node is incorrect or has an incorrect ancestor for this operation.

unsigned short DATA_CLONE_ERR

If the object can not be cloned.

ATTRIBUTES

readonly unsigned short code

16-bit error code. For the possible values for this attribute, see DOMException.

This attribute is read-only.

readonly DOMString name

An error type. The name attribute must return the value it was initialized with. This attribute can have one of the following values:

  • UnknownError - An unknown error has occurred.
  • InvalidValuesError - The content of an object does not contain valid values.
  • IOError - An error occurred in communication with the underlying implementation and so the requested method cannot be completed.
  • ServiceNotAvailableError - The requested service is not available.

For other possible values for this attribute, see the values defined in DOM error types

This attribute is read-only.

readonly DOMString message

An error message that describes the details of an encountered error. This attribute is mainly intended to be used for developers rather than end users, so it should not be used directly in the user interfaces as it is.

This attribute is read-only.

2.10. WebAPIError

Generic error interface.

    interface WebAPIError {


        readonly attribute DOMString name; 
            

        readonly attribute DOMString message;
  };

This interface will be used by the APIs in order to return them in the error callback of asynchronous methods.

Code example
 function successCallback(contacts) {
   // The returned contacts are sorted by first name (ascending)
   console.log(contacts.length + " contacts found.");
 }

 // Define an error callback
 function errorCallback(error) {
     // error parameter is a WebAPIError object.
     if (error.name == "NotFoundError") {
        // the contacts are not found.
     }
 }
 
 // Send request on contact address book.
 webapis.contact.getDefaultAddressBook().find(successCallback, errorCallback);
 

 }
 

ATTRIBUTES

readonly DOMString name

An error type.

The name attribute must return the value it was initialized to. Possible values are the ones defined in DOM error types.

Extra values which will not be covered in DOM error types can be defined including:

  • UnknownError - An unknown error has occurred.
  • InvalidValuesError - The content of an object does not contain valid values.
  • IOError - An error occurred in communication with the underlying implementation and so the requested method cannot be completed.
  • ServiceNotAvailableError - The requested service is not available.

These values SHOULD NOT be minted if the meaning of exception or error is simular with predefined error types.

This attribute is read-only.

readonly DOMString message

An error message that describes the details of the error encountered. This attribute is not intended to be used directly in the user interfaces as it is mainly intended to be useful for developers rather than end-users

This attribute is read-only.

2.11. SuccessCallback

This interface is used in methods that do not require any return value in the success callback. In case of successful execution of an asynchronous call, SuccessCallback or an API defined callback must be called immediately to notify the user.

  [Callback=FunctionOnly, NoInterfaceObject]
  interface SuccessCallback {

    void onsuccess();
  };
Code example
     function onSuccess() {
         console.log("Application terminated successfully");
     }
     webapis.application.kill(onSuccess, anApp);
 

METHODS

onsuccess

Method invoked when the asynchronous call completes successfully.

Signature
void onsuccess();

2.12. ErrorCallback

This cinterface is used in methods that only an error as input parameter in the error callback. If an invalid function (such as null) is passed to the API that accepts ErrorCallback, it silently fails and there is no further action.

  [Callback=FunctionOnly, NoInterfaceObject]
  interface ErrorCallback {
 

    void onerror (WebAPIError error);
  };
Code example
  // Define the error callback.
  function onError(error) {
    console.log(error.message);
  }

  // Define the success callback.
  function onSuccess(services) {
     //send a message using the found service
  }
  webapis.messaging.getMessageServices("messaging.sms", onSuccess, onError);
 

METHODS

onerror

Method that is invoked when the error occurs.

Signature
void onerror(WebAPIError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: Generic error.

3. Full WebIDL

module WebAPIs {
    

  enum FilterMatchFlag { "EXACTLY", "FULLSTRING", "CONTAINS", "STARTSWITH", "ENDSWITH", "EXISTS" };
  

  enum SortModeOrder { "ASC", "DESC" };
  

  enum CompositeFilterType { "UNION", "INTERSECTION" };


  typedef sequence<DOMString> StringArray;


  typedef sequence<unsigned short> UnsignedShortArray;


  typedef sequence<short> ShortArray;
  

  [NoInterfaceObject] interface WindowWebAPIs {
    readonly attribute WebAPIs webapis;
  };

  Window implements WindowWebAPIs;


  [NoInterfaceObject] interface WebAPIs {

  };


  [NoInterfaceObject] interface AbstractFilter {
  };
  

  [Constructor(DOMString attributeName, optional FilterMatchFlag? matchFlag, optional any matchValue)]

  interface AttributeFilter : AbstractFilter {


    attribute DOMString attributeName;

    attribute FilterMatchFlag matchFlag;


    attribute any matchValue;
  };  

  [Constructor(DOMString attributeName, optional any initialValue, optional any endValue)]

  interface AttributeRangeFilter : AbstractFilter {

    attribute DOMString attributeName;


    attribute any initialValue;


    attribute any endValue;
  };

  [Constructor(CompositeFilterType type, optional AbstractFilter[]? filters)]

  interface CompositeFilter : AbstractFilter {


    attribute CompositeFilterType type;
    

    attribute AbstractFilter[] filters;
  };
  
 [Constructor(DOMString attributeName, optional SortModeOrder? order)] 

  interface SortMode {

    attribute DOMString attributeName;    


    attribute SortModeOrder order setraises(WebAPIException);
  };
  
[Constructor(double latitude, double longitude)]  

  interface SimpleCoordinates {


    attribute double latitude setraises(WebAPIException);


    attribute double longitude setraises(WebAPIException);
  };


    interface WebAPIException {


        readonly attribute unsigned short code;


        readonly attribute DOMString name; 
            

        readonly attribute DOMString message;
                   

        const unsigned short INDEX_SIZE_ERR = 1; 
        

        const unsigned short DOMSTRING_SIZE_ERR = 2; 
        

        const unsigned short HIERARCHY_REQUEST_ERR = 3; 
        

        const unsigned short WRONG_DOCUMENT_ERR = 4; 


        const unsigned short INVALID_CHARACTER_ERR = 5;


        const unsigned short NO_DATA_ALLOWED_ERR = 6; 


        const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7; 


        const unsigned short NOT_FOUND_ERR = 8; 


        const unsigned short NOT_SUPPORTED_ERR = 9; 


        const unsigned short INUSE_ATTRIBUTE_ERR = 10; 


        const unsigned short INVALID_STATE_ERR = 11; 


        const unsigned short SYNTAX_ERR = 12; 


        const unsigned short INVALID_MODIFICATION_ERR = 13; 


        const unsigned short NAMESPACE_ERR = 14; 


        const unsigned short INVALID_ACCESS_ERR = 15; 


        const unsigned short VALIDATION_ERR = 16; 
 

        const unsigned short TYPE_MISMATCH_ERR = 17; 
 

        const unsigned short SECURITY_ERR = 18; 
 

        const unsigned short NETWORK_ERR = 19; 
 

        const unsigned short ABORT_ERR = 20; 


        const unsigned short URL_MISMATCH_ERR = 21; 
 

        const unsigned short QUOTA_EXCEEDED_ERR = 22; 
 

        const unsigned short TIMEOUT_ERR = 23; 
 

        const unsigned short INVALID_NODE_TYPE_ERR = 24; 


        const unsigned short DATA_CLONE_ERR = 25; 
  };
  

    interface WebAPIError {


        readonly attribute DOMString name; 
            

        readonly attribute DOMString message;
  };
  

  [Callback=FunctionOnly, NoInterfaceObject]
  interface SuccessCallback {

    void onsuccess();
  };



  [Callback=FunctionOnly, NoInterfaceObject]
  interface ErrorCallback {
 

    void onerror (WebAPIError error);
  };
};