WebAPI/LogAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
(23 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Proposer ==
José M. Cantera, Telefónica, jmcf@tid.es
== Use Cases ==
== Use Cases ==


To record the history of user activity with the device, particularly with communication services (Phone Calls, Messages, Social Networks, etc.)  
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 ===
=== Consumers ===
Line 9: Line 16:
=== Producers ===  
=== Producers ===  


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


== WebIDL ==
== WebIDL ==


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


interface LogIterator {
// The iterator will be initialized with a window indicated in the iteration parameters
   DOMRequest next(optional unsigned short n);
[NoInterfaceObject]
   attribute boolean hasMore;
interface DOMIterator {
   attribute unsigned long position;
   DOMRequest next();  // request to refresh the window of objects with the next
   readonly attribute LogEntry[] values;
  DOMRequest prev();  // request to refresh the window of objects with the prev
  DOMRequest skipTo(unsigned long chunk);
   readonly attribute boolean hasMore;  
   readonly attribute unsigned long count; // total number of objects
   readonly attribute any[]? values;   // Contains the current window of objects
  readonly attribute chunkSize;
};
 
dictionary LogFindFilter {
  DOMString? contactId;
  Date? from;  // for defining a time interval
  Date? to;      // for defining a time interval
  DOMString? service;  // to filter by service
  DOMString? type;    // to filter by Log type
};
};


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


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


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


Line 64: Line 91:
== Examples ==
== Examples ==


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


<pre>
<pre>
var filter = {maxNumber: 20};
var pageOptions = {maxNumber: 30, chunkSize: 10};
var req = navigator.mozLog.find(filter);
var req = navigator.mozLog.find(null,pageOptions);
req.onsuccess = function(e) {
req.onsuccess = function(e) {
   var iterator = e.target.result;
   var iterator = e.target.result;
    
    
   var req2 = iterator.next(10);
   doSomething(iterator.values);
    req2.onsuccess = function(e) {
 
      var entries = e.target.result;
  if(iterator.hasMore) {
      if(iterator.hasMore) {
    iterator.next();
        iterator.next(10);
      }
   }
   }
}
}
</pre>
</pre>


Get latest 10 log entries corresponding to a contactId  
Get all the log entries corresponding to a contactId  


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

Latest revision as of 23:53, 1 October 2014

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 NavigatorLog {
    readonly attribute LogManager mozLog;
};

Navigator implements NavigatorLog;

[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 LogFindFilter filter,optional IteratorOptions iopts);
        
   attribute Function? onentryadded;  // To listen for log changes
 };

// The iterator will be initialized with a window indicated in the iteration parameters
[NoInterfaceObject]
interface DOMIterator {
  DOMRequest next();   // request to refresh the window of objects with the next
  DOMRequest prev();   // request to refresh the window of objects with the prev
  DOMRequest skipTo(unsigned long chunk);
  readonly attribute boolean hasMore; 
  readonly attribute unsigned long count;  // total number of objects
  readonly attribute any[]? values;   // Contains the current window of objects
  readonly attribute chunkSize;
};

dictionary LogFindFilter {
   DOMString? contactId;
   Date? from;   // for defining a time interval
   Date? to;       // for defining a time interval
   DOMString? service;  // to filter by service
   DOMString? type;     // to filter by Log 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;            // To clear all the entries corresponding to a tel number
};

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;
  
  var logEntries = iterator.values;
  for(var c = 0; c < logEntries.length; c++) {
    window.console.log('LogEntry: ', logEntries[c].type,logEntries[c].timestamp);
  }

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