WebAPI/LogAPI: Difference between revisions
< WebAPI
Jump to navigation
Jump to search
(→WebIDL) |
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 | DOMRequest find(optional LogFindFilter filter,optional IteratorOptions iopts); | ||
attribute Function onentryadded; | attribute Function? onentryadded; // To listen for log changes | ||
}; | }; | ||
interface | // The iterator will be initialized with a window indicated in the iteration parameters | ||
DOMRequest next( | [NoInterfaceObject] | ||
attribute boolean hasMore; | interface DOMIterator { | ||
attribute unsigned long | DOMRequest next(); // request to refresh the window of objects with the next | ||
readonly attribute | 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 | 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 { | 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 { | 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 | Get latest global 30 log entries (ordered by timestamp, newest to oldest) in chunks of 10 | ||
<pre> | <pre> | ||
var | var pageOptions = {maxNumber: 30, chunkSize: 10}; | ||
var req = navigator.mozLog.find( | 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; | ||
doSomething(iterator.values); | |||
if(iterator.hasMore) { | |||
iterator.next(); | |||
} | } | ||
} | } | ||
</pre> | </pre> | ||
Get | 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(); } }