WebAPI/LogAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(63 intermediate revisions by one other user not shown)
Line 1: Line 1:
Use Cases: To record the history of user activity with the device, particularly with communication services (Phone Calls, Messages, Social Networks, etc.)  
== 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 ==


<pre>
<pre>
interface LogsManager {
[NoInterfaceObject]
     DOMRequest add(in LogEntry entry);
interface NavigatorLog {
     DOMRequest remove(DOMString entryId);
    readonly attribute LogManager mozLog;
     DOMRequest removeOld(DOMTimestamp to,optional DOMString contactId)
};
    DOMRequest getLast(unsigned long number,);
 
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
};


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


[Constructor(in LogEntryProperties properties)]
[Constructor(LogEntryProperties properties)]
interface LogEntry : LogEntryProperties {
interface LogEntry : LogEntryProperties {
   readonly attribute DOMString id;
   readonly attribute DOMString id;
   readonly attribute Date timestamp;                  // When this happened
   readonly attribute DOMTimestamp timestamp;                  // When happened
};
</pre>
 
== Examples ==
 
Get latest global 30 log entries (ordered by timestamp, newest to oldest) in chunks of 10
 
<pre>
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();
  }
}
}
</pre>
Get all the log entries corresponding to a contactId


<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();
  }
}