We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Personal Data Services API Specification (PRELIMINARY) - FIWARE Forge Wiki

Personal Data Services API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Personal Data Services API Introduction

This section covers all the APIs related to Personal Data Services. This includes the following functional blocks:

  • Contacts
  • Calendar
  • Gallery
  • File system Access
  • Personal Data Interface Availability

Please check the following Legal Notice (essential patents license) to understand the rights to use these specifications.

How to Read This Document

Each of the functional blocks covered above are described in WebIDL. Where a Functional Block's API is simply a realisation of an existing standards based specification, this document will link directly to the relevent standards bodies WebIDL specification document. This is a prudent step as FI-WARE is an integration project, and will by necessity combine already existing API specifications.

Non RESTfull API

This specification outlines an API which is JavaScript based. This is because the API is intended to be used by applications running on a device. In this situation we are invoking local services and a RESTful interface would add a layer of complicity which is overly complicated and ultimately unnecessary.

API Change History

Version Date Author Comment
0.1 13th June 2012 Chris Woods (Intel) Initial draft API Version
1.0 6th November 2012 Chris Woods (Intel) Additional documentation and API changes. First version to be considered for release
1.1 21st May 2013 Chris Woods (Intel) Content update, and formatting changes. API remains the same
1.2 13 June 2013 Chris Woods (Intel) Added Gallery API
1.3 26 June 2013 Chris Woods (Intel) Added File System API - initial draft

Intended Audience

This specification is intended for software developers who will use the API, and for those who will implement the specification. It is assumed that the reader is familiar with WebIDL.

Introduction to the Contacts API

The FI-WARE Contact's API is an extension to the W3C Contacts API. It also considers the Boot to Geko Contacts API. The W3C API provides a read only interface. The Boot to Geko API provides both read and write capabilities. However the Boot to Geko API did not achieve the design goals which have been set. The modifications to the W3C Contacts API presented here provides both Read and Write support, and achieves the design goals outlined below. This API forms part of the Connected Device Interface (CDI).

Link to Contacts API W3C Working Draft 16 June 2011

The FIWARE.Feature.I2ND.CDI.PersonalDataServices.Contacts contacts API is based on the W3C Contact's specification. Specifically the specification published as "Contacts API W3C Working Draft 16 June 2011". A link to this version of the specification is provided here: http://www.w3.org/TR/2011/WD-contacts-api-20110616/

The Contact's API provides access to a client based address book. Where a device has multiple address books, such as in the case of Android, a single unified address book view will be presented.

The Contacts' API is expressed in WebIDL. The following provides an overview of the final API for the CDI’s Contacts Functional Block implementation.

Design Goals

The extensions to the W3C API described here attempt to address the following design goals.

  1. Align with existing W3C API (unified address book)
    Note: W3C defines a unified address book. This model is supported by Mozilla & PhoneGap, but not by Tizen. Tizen offers individual address books.
  2. Extensible and supportive of real world workloads
    Note: The existing PhoneGap model requires the developer to load each and every contact in order to apply any changes via Contact member functions. This can be limiting, placing the functions in this locations means that the entire contact has to be loaded from disk before being manipulated. There are no methods to:
    • delete a contact by ID
    • preform batch operations (delete a range of IDs, save a collection of contacts)
    Additionally it would not be possible to add these batch operations to the contact object, forcing any new functions which address this functionality to be located on the collection object. This will result in an inconsistent structure.
  3. Ease of use
    Note: Ensuring the API is easy and intuitive to use is important. The Mozilla API should a two phase constructor for the contact object. The developer preforms a new, then calls an “init” member function to setup the object prior to use. PhoneGap requires the user to call a factory function to create an instance of a contact object – even though a constructor exists. This is inconsistent.

Authentication

This API should only be available to applications (web applications / webapps) which have been installed on the device. The installation procedure should verify an applications request to access the contact’s APIs and obtain user consent before installing the application. Following this, at runtime it can be assumed that the user has granted access for this application to access the contacts API.

Faults

Any faults encountered when invoking the Contacts API will result in an error function being invoked. The call back will contain an error code. The reader will find the list of error codes outline below.

Modifications to the Contacts API - W3C Working Draft 16 June 2011

The FIWARE.Feature.I2ND.CDI.PersonalDataServices.Contacts contacts API is based on the W3C's "Contacts API W3C Working Draft 16 June 2011", with modifications to support writing contact data and adhering to the design principles outlined above. The exact changes to the W3C specification are outlined below.

Addition of APIs for adding and modifying contacts

The contacts interface has been extended with the following new functions (shown in red):

[NoInterfaceObject]
interface Contacts {
        caller void find (
                          DOMString[] fields,
                          ContactFindCB successCB,
                          optional ContactErrorCB errorCB
                          optional ContactFindOptions options
        );

        caller void save(
                          Contact contactObj,
                          ContactSaveCB successCB,
                          optional ContactErrorCB failureCB
        );
        caller void remove(
                          DomString contactId,
                          ContactRemoveCB removeCB,
                          optional ContactErrorCB failureCB
        );

};


Contacts Methods

save

Save the contact in the contact database. If the contact already exists then overwrite the existing contact object with the object provided by in contactObj. This method takes two or three arguments. When called it starts the following save contacts process:
  1. Let contactObj be the contact object indicated by the method's first argument
  2. Let successCB (success call back) be the callback indicated by the method's second argument
  3. Let errorCB (error call back) be the callback indicated by the method's third argument
  4. If successCB is null, then throw a TypeError (as defined in WEBIDL)
  5. If contactObj is null, then throw a TypeError (as defined in WEBIDL)
  6. Return, and run the remaining steps asynchronously
  7. If contactObj has a property id and its value is none null and not empty, then run these sub steps:
    1. Search the database for any other contact with the same id value
    2. For each contact returned from the search; delete the contact object from the database
  8. If contactObj does not have a property id or the value is null or empty, then run these sub steps:
    1. Allocate a new id value ensuring the value is unique and not assigned to any other existing contact objects
    2. Assign the new id value to the contactObj
  9. Create a new contact object in the database which exactly replicates the contactObj supplied
  10. Let result be contactObj (now populated with an accurate ID value, if not supplied with one)
  11. Queue a task to invoke successCB with result as its argument


Parameter Type Nullable Optional Description
contactObj Contact No No The contact object to update or insert in the database
successCB ContactSaveCB No No Function to call when the asynchronous operation completes successfully
failureCB ContactErrorCB No Yes Function to call when the asynchronous operation fails


remove

Removes a contact with a specified Id from the persisted contact database. This method takes two or three arguments. When called it starts the following save contacts process:
  1. Let contactId be the id value indicated by the method's first argument
  2. Let successCB (success call back) be the callback indicated by the method's second argument
  3. Let errorCB (error call back) be the callback indicated by the method's third argument
  4. If successCB is null, then throw a TypeError (as defined in WEBIDL)
  5. If contactId is null, or an empty string then throw a TypeError (as defined in WEBIDL)
  6. Return, and run the remaining steps asynchronously
  7. Search the database for any other contact with the same id value
  8. If a contact is found with the same id as contactId, then delete that contact from the database and then queue a task to invoke successCB
  9. If a contact is not found with the same id as contactId and failureCB is not null and has been provided by the caller then, queue a task to invoke failureCB with the parameter NOT_FOUND.
Parameter Type Nullable Optional Description
contactObj DOMString No No The id of the contact object to delete from the database
successCB ContactRemoveCB No No Function to call when the asynchronous operation completes successfully
failureCB ContactErrorCB No Yes Function to call when the asynchronous operation fails


Addition of call back / event functions for saving and modifying contacts

The contacts interface uses the following new call back functions (shown in red):


[Callback=FunctionOnly, NoInterfaceObject]
interface ContactSaveCB  {       
        void onsuccess(Contact contact);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactRemoveCB  {       
        void onsuccess();
};

ContactSaveCB Methods

onsuccess

No exceptions. No return value.
Parameter Type Nullable Optional Description
contact Contact No No The contact saved to the database with a value id value.

ContactRemoveCB Methods

onsuccess

No parameters. No exceptions. No return value.

Addition of new ContactError values supporting saving and modifying of contacts

The contacts interface uses the following new error values (shown in red):

[NoInterfaceObject]
interface ContactError {
        const unsigned short              UNKNOWN_ERROR = 0;
        const unsigned short              INVALID_ARGUMENT_ERROR = 1;
        const unsigned short              TIMEOUT_ERROR = 2;
        const unsigned short              PENDING_OPERATION_ERROR = 3;
        const unsigned short              IO_ERROR = 4;
        const unsigned short              NOT_SUPPORTED_ERROR = 5;
        const unsigned short              PERMISSION_DENIED_ERROR = 20;
        const unsigned short              NOT_FOUND = 404;
        readonly attribute unsigned short code;
};

Change where ServiceContacts Interface is exposed

The ServiceContacts interface is exposed by the $cdi.pds object within FI-WARE and not by the Navigator object as specified by the W3C Draft specification.

Detecting Contacts API Support

Not all devices have an address book, and therefore not every device will have a contacts API. To address this CDI provides a way to determining if the device upon which your code is executing has support for the Contacts API. This can be done via $cdi.pds.availability.contacts property the following code demonstrates how this might be used:

    if ( $cdi.pds.availability.contacts ) {
        // Contacts API is available...
    } else {
        // Contacts API is not availabkle...
    }



Introduction to the Gallery API

The Gallery API is based on the Webinos Media Content API and on the Tizen Content API. It implements the FIWARE.Feature.I2ND.CDI.PersonalDataServices.Gallery feature. This feature is a subset of the total functionality provided by bot the Tizen and Webinos implementations. As such significant changes have been made from these originating APIs. These changes are outlined below.

Design Goals

The goals of the API and it's design are to provide simple, straight forward access to media content stored on the device. The developer will not need to worry about where on the device such content is located, just that the content is available for playback or display.

Authentication

This API should only be available to applications (web applications / webapps) which have been installed on the device. The installation procedure should verify an applications request to access the contact’s APIs and obtain user consent before installing the application. Following this, at runtime it can be assumed that the user has granted access for this application to access the API.

Faults

Any faults encountered when invoking the Contacts API will result in an error function being invoked. The call back will contain an error code. The reader will find the list of error codes outlined below. Additional developer errors, e.g. passing incorrect parameters, will result in an exception being thrown.

Modifications from the Webinos and Tizen Implementations

There are three key major areas of functionality which are present in the Tizen and Webinos implementations and not present in the I2ND, CDI implementaiton. These are detailed below: 1. The Tizen and Webinos implementation contained significant functionality for editing or modifying media content. This is out of the scope of the CDI Gallery feature and support for this has been removed. 2. The Tizen and Webinis implementation contained support for media folders, physical device locations where media could be stored. These are out of scope for the CDI implementation. Supporting this functionality contradicts our design goals of offering a simple API. This exposes to the developer implementation details of where media is stored on the device. The location differences have no impact on the resulting functionality; if the media is located in folder A it can be played back just as easily as media stored in folder B. 3. The Webinos implementation introduced support for pending operations and the ability to cancel operations which were in progress. This functionality is not supported in the CDI implementation.

Gallery API

Given the signifant changes from the base APIs the Gallery API is documented in full below. The following IDL outlines the functionality offered by the CDI Gallery API.

 
  enum MediaItemType { "IMAGE", "VIDEO", "AUDIO", "UNKNOWN" };
 
  enum MediaLyricsType { "SYNCHRONIZED", "UNSYNCHRONIZED" };
 
  enum MediaImageOrientation { "NORMAL", "FLIP_HORIZONTAL", "ROTATE_180", "FLIP_VERTICAL", "TRANSPOSE", "ROTATE_90", "TRANSVERSE", "ROTATE_270" };
 
  typedef DOMString MediaItemId;
 
  [NoInterfaceObject] interface MediaSource {
 
    readonly attribute boolean available;                  
    void findItems(MediaItemArraySuccessCallback successCallback,
                   optional ErrorCallbackErrorCallback? errorCallback,
                   optional AbstractFilter? filter,
                   optional SortMode? sortMode,
                   optional unsigned long? count,
                   optional unsigned long? offset);                  
 
};
 
  [Callback=FunctionOnly, NoInterfaceObject] interface MediaItemArraySuccessCallback {
    void onsuccess(MediaItem[] items);
  };
 
  [NoInterfaceObject] interface MediaItem {
 
    readonly attribute MediaItemId id;
 
    readonly attribute MediaItemType type;
 
    readonly attribute DOMString mimeType;
 
    readonly attribute DOMString title;
 
    readonly attribute DOMString itemURI;
 
    readonly attribute DOMString[]? thumbnailURIs;
 
    readonly attribute Date? releaseDate;
 
    readonly attribute Date? modifiedDate;
 
    readonly attribute unsigned long? size;
 
    readonly attribute DOMString? description;
 
    readonly attribute float? rating;
  };
 
  [NoInterfaceObject] interface MediaVideo : MediaItem {
 
    readonly attribute SimpleCoordinates? geolocation;
 
    readonly attribute DOMString? album;
 
    readonly attribute DOMString[]? artists;
 
    readonly attribute unsigned long duration;
 
    readonly attribute unsigned long width; 
 
    readonly attribute unsigned long height;     
 
    readonly attribute unsigned long? playedTime;
 
    readonly attribute unsigned long? playCount;
  };
 
 
  [NoInterfaceObject] interface MediaLyrics {
 
    readonly attribute MediaLyricsType type;
 
    readonly attribute unsigned long[] timestamps;
 
    readonly attribute DOMString[] texts;
  };
 
  [NoInterfaceObject] interface MediaAudio : MediaItem {
 
    readonly attribute DOMString? album;
 
    readonly attribute DOMString[]? genres;
 
    readonly attribute DOMString[]? artists;
 
    readonly attribute DOMString[]? composers;
 
    readonly attribute MediaLyrics? lyrics;
 
    readonly attribute DOMString? copyright;
 
    readonly attribute unsigned long? bitrate;
 
    readonly attribute unsigned short? trackNumber;
 
    readonly attribute unsigned long duration;
 
    readonly attribute unsigned long? playedTime;
 
    readonly attribute unsigned long? playCount;
  };
 
  [NoInterfaceObject] interface MediaImage : MediaItem {
 
    readonly attribute SimpleCoordinates? geolocation;
 
    readonly attribute unsigned long width; 
 
    readonly attribute unsigned long height;     
 
    readonly attribute MediaImageOrientation? orientation;
 
  };
 
 
  enum FilterMatchFlag { "EXACTLY", "FULLSTRING", "CONTAINS", "STARTSWITH", "ENDSWITH", "EXISTS" };
 
  enum SortModeOrder { "ASC", "DESC" };
 
  enum CompositeFilterType { "UNION", "INTERSECTION" };
 
  [NoInterfaceObject] interface AbstractFilter {
  };
 
  [Constructor(CompositeFilterType type, optional AbstractFilter[]? filters)]
  interface CompositeFilter : AbstractFilter {
    attribute CompositeFilterType type;
 
    attribute AbstractFilter[] filters;
  };
 
  [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(DOMString attributeName, optional SortModeOrder? order)]
  interface SortMode {
    attribute DOMString attributeName;
 
    attribute SortModeOrder order;
  };


findItems

Find media items on the device which match the conditions specified by the filter

 
$cdi.pds.gallery.findItems(successCallback, errorCallback, filter, sortMode, count, offset)

This method searches the device for all media content which matches the conditions outlined by the filter specified. If no content items match, or there are no content items on the device the function will call the successCallback function with an array with no item (zero length).

Parameters

  • successCallback : Callback method, invoked when successfully serviced issued query
  • errorCallback (optional, can be null): Callback invoked when an error has occurred
  • filter (optional, can be null): the filter to apply when searching for media content. If no filter is specified or parameter is null then no filter will be used (all contents returned).
  • sortMode (optional, can be null): Specifies the sort order used to present the results
  • count (optional, can be null): The max number of content items to return. If not specified the value 100 is used. If count is zero an exception will be thrown.
  • offset (optional, can be null): Offset in the results set to use. Can be used to implement paging.



Exceptions
If invalid parameters are specified then an exception with the string “ERROR: find function parameters are not valid!” will be thrown. The console output will contain additional information about the exact error.



Example Code
The following code example illustrates how to the the gallery API to search for audio content from the UK artist, "Jamiroquai's" album "Travelling Without Moving". Please not the use of constants from the $cdi object e.g. $cdi.gallery.FilterMatchFlag.EXACTLY.

// Filter for audio items only, we're not interested in video items
var typeFilter = new $cdi.pds.gallery.AttributeFilter(
    "type",
    $cdi.gallery.FilterMatchFilag.EXACTLY,
    $cdi.gallery.MediaItemType.AUDIO
    );
 
// Filter for audio items from "Jamiraquai"
var artistsFilter = new $cdi.pds.gallery.AttributeFilter(
    "artists"
    $cdi.gallery.FilterMatchFlag.EXACTLY,
    "Jamiraquai");
 
// Filter for audio items from Jamiaraquai's album called "Travelling Without Moving"
var albumFilter = new $cdi.pds.gallery.AttributeFilter(
    "album",
    $cdi.gallery.FilterMatchFlag.EXACTLY,
    "Travelling Without Moving");
 
var completeFilter = new $cdi.pds.gallery.CompositeFilter(
    $cdi.pds.gallery.CompositeFilterType.UNION,
    [typeFilter, albumFilter, artistFilter]);
 
 var sortMode = new $cdi.pds.gallery.SortMode(
     "trackNumber",
    $cdi.pds.gallery.SortModeOrder.ASC);
 
 
// Call the findItems function and handle the response, with code to handle exceptions, and error responses.
try {
    $cdi.pds.gallery.findItems(
         function(items) {
            // success response - construct a string (searchResults ) with an unordered list of track details
            var searchResults = "<ul>";
            for (var i = 0; i < items.length; i++) {
                searchResults += ( "<li> " + items[i].trackNumber + ". <a href='" + items[i].contentURI + "'>");
                searchResults += items[i].title;
                searchResults += ( "</a> (" + items[i].duration + " seconds)</li>")           
            }
            searchResults+= "</ul>";
            // Assuming the use of jQuery, update an on screen DIV with id "output" (not shown in code example)
            // and update it with contents of the searchResults string
            $("#output").html( searchResults );
        },
        function(error) { // error callback
            $("#output").html("An error has occured... ");
        },
        completeFilter,
        sortMode); // count and offset excluded   
} catch( exception ) {
    $("#output").html("An exception occured <br/>" + exception );
}



Introduction to the File System API

The FI-WARE File System API is an implementation of the W3C File System APIs. These profile read and write access to the devices file system structures. With the exception of changing the name space for gaining access to the file system APIs the FI-WARE specifications are identical to the W3C specifications.

Link to File System API W3C Specifications

The W3C breaks the file system API work down into three specifications. Each covers a distinct form of functionality. This FI-WARE specification encompasses all three. The three specifications are described below along with links to the W3C originals:

  • FIleAPI
This specification provides read only access to file objects
Link to specification – FileAPI, W3C Working Draft 20 October 2011
  • FileAPI: Writer
This specification provides write access to file objects. This API relies on the FIleAPI (above) being present before it can be utilised.
Link to the specification – FileAPI: Writer, W3C Working Draft 17th April 2012
  • FileAPI: Directories and System
This specification provides an API to navigate and interrogate the file system structures present on the device. It also provides a way for applications to be granted a sandboxed section of the user’s local filesystem. This API depends on the FileAPI, and FileAPI: Write (both above). Before it can be utilised.
Link to the specification – FileAPI: Directories and System, W3C Working Draft 17th April 2012

Design Goals

File systems and their representations have been around since the 1960s and are a well-defined concept. The design goals here are to align with the W3C specifications as much as possible, to help the web application development community by providing a single method of accessing this well understood construct.

Authentication

This API should only be available to applications (web applications / webapps) which have been installed on the device. The installation procedure should verify an applications request to access the contact’s APIs and obtain user consent before installing the application. Following this, at runtime it can be assumed that the user has granted access for this application to access the contacts API.

Faults

Any faults encountered when invoking the File System APIs will result in an error function, or exception being invoked. The error response will contain an error code.

Modifications to the File System API W3C Specifications

The only modification to the three specifications is the namespace to use when referencing them. The W3C specifications use the global namespace. In CDI the name space to use is $cdi.pds.fsa, an example would be:

    $cdi.pds.fsa.LocalFileSystem.requestFileSystem("PERSISTENT", 64*1024,
                function(fs){
                    print("local file system accessed");
                    print("got : " + fs.name );
                    localFs = fs;
                });

File System Access Availability

CDI includes the ability to check for File System Access support, this is necessary as not every system has the ability to provide File System Access. If the $cdi.pds.availability.fsa variable is set to true then the File System Access API is available on the system upon which the code is executing:

    function Startup() {
        if ( $cdi.pds.availability.fsa) {
            print("FSA is supported!");
            // file system access
            $cdi.pds.fsa.LocalFileSystem.requestFileSystem("PERSISTENT", 64*1024,
                function(fs){
                    print("local file system accessed");
                    print("got : " + fs.name );
                    localFs = fs;
                });            
        } else {
            print("no fsa support");
        }           
    }
</pre>
Personal tools
Create a book