WebAPI/LogAPI
From MozillaWiki
< WebAPI
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(); } }