WebAPI/LogAPI

Proposer

José M. Cantera, Telefónica, jmcf@tid.es

Use Cases

To record the history of user activity with the device, particularly with communication services (Phone Calls, Messages, Social Networks, etc.) The Communications Log can have different views: Global or Per-Contact

Using the API the occurrence of incoming calls, missed calls, incoming messages, outgoing messages etc. is automatically recorded.

Consumers

• Comms Log Application (Global for the user and per-contact)

Producers

• Dialer, SMS, e-mail, Facebook, Twitter, ...

WebIDL

[NoInterfaceObject]
interface LogManager : EventTarget  {
    DOMRequest put(LogEntry entry);
    DOMRequest delete(DOMString entryId); // Delete one entry
    DOMRequest clear(LogClearOptions coptions);  // To clear the log for maintenance purposes
    // Entries are always returned ordered by timestamp (desc)
    DOMRequest find(optional LogFindOptions options,optional IteratorOptions iopts);
        
   attribute Function? onentryadded;
 };

// The iterator will be initialized with a window indicated in the iteration parameters
[NoInterfaceObject]
interface DOMIterator {
  DOMRequest next(optional unsigned short n);   // returns the next window
  attribute boolean hasMore;
  attribute unsigned long position; // points always to the element that will be the first returned by the window 
  readonly attribute unsigned long count;  // total number of objects
  readonly attribute any[] values;   // Contains the current window of objects
};

dictionary LogFindFilter {
   DOMString? contactId;
   Date? from;
   Date? to;
   DOMString? service;
   DOMString? type;
};

dictionary LogClearOptions {
  Date deadline;  // To clear all the entries older than the date passed as parameter
  DOMString? contactId;  // To clear all the entries corresponding to a contact
  DOMString? tel;
};

dictionary IteratorOptions {
  unsigned long? maxRecords = -1;  // Max number of records to be returned (-1 means all)
  unsigned long? chunkSize = 10;    // Chunk size for the iterator
};

interface LogEntryProperties {
   attribute DOMString type;  // possible values: ['incoming', 'outgoing'']
   attribute DOMString? status;  // [missed, new]         
   attribute DOMString[]? contactId;  // ContactId     
   attribute DOMString[]? tel;  // Tel number if not in contacts
   attribute DOMString? objectId;  // Object id (for example SMS message on the SMS database)   
   attribute DOMString service;  // oneOf ['SMS', 'Telephony', 'Facebook', 'Twitter'] 
   attribute DOMString? title;             
   attribute DOMString? description;
   attribute any? extra;  // Any extra data to be used by applications
};

[Constructor(LogEntryProperties properties)]
interface LogEntry : LogEntryProperties {
   readonly attribute DOMString id;
   readonly attribute DOMTimestamp timestamp;                  // When happened
};

Examples

Get latest global 30 log entries (ordered by timestamp, newest to oldest) in chunks of 10

var pageOptions = {maxNumber: 30, chunkSize: 10};
var req = navigator.mozLog.find(null,pageOptions);
req.onsuccess = function(e) {
  var iterator = e.target.result;
  
  doSomething(iterator.values);

  if(iterator.hasMore) {
     iterator.next();
  }
}

Get all the log entries corresponding to a contactId

var filterOptions = {contactId: 'ax1234'};
var req = navigator.mozLog.find(filterOptions);
req.onsuccess = function(e) {
  var iterator = e.target.result;
  
  for(var c = 0; c < iterator.values.length; c++) {
    window.console.log('LogEntry: ', logEntries[c].type,logEntries[c].timestamp);
  }

  if(iterator.hasMore) {
     iterator.next();
  }
}