BONDI

Lunar calendar should be supported in the calendar and contacts API.

http://en.wikipedia.org/wiki/Lunar_calendar

Feedback from ETRI - Lunar calendar is very important in Asia and is not taken into account so far in BONDI.

BONDI API includes several “filter” interfaces.
E.g. ContactFilter, IncomingSMSEventFilter
It is not specified how those filters are to be used.
The first assumption is that the values from  the filter object must match the ones in the records from the collections.
This may work nicely with string values, but it has issues when filtering dates or integer values.
We have therefore initialDueDate and finalDueDate in TaskFilter.
However, this solution does not scale to other properties and interfaces.
Therefore I would suggest to redefine all the filter interfaces to be just strings with SQL-like (or so) syntax that use  “<”, “>”, “=”, “contains/like”, “*” tokens and relate them (e.g. via extended attributes or doxygen keyword) to the relevant interfaces that specify the properties to be used.

Consistency and current underspecification

Contacts API


1. Multiple Address Books can be retrieved but these have fixed naming (i.e. phone, sim and device address books). Can we have other address books (i.e. networked, work, home, myservice, ...)?

2. In Section 3.2 it states the following: 'Addressbook availabe are: SIM Device memory AddressBook'. I think we are missing 'phone' from this list. Also there is a spelling mistake: 'availabe' should be 'available'.

CR: Section 3.2: '...Addressbook objects that are available include: Phone, SIM, Device, and Memory AddressBook objects.'.

3. ** Backwards compatibility is broken between 1.01 and 1.1. ContactOptions.telephone in 1.01 and ContactOptions.phoneNumbers in 1.1. Regardless of the change of naming (which already breaks backward compatibility) the type of these attributes has also changed, breaking backward compatibility.

CR:
- Add '[Deprecated] attribute DOMString telephone;'
- Add the following descriptive text: 'When the deprecated telephone attribute is used by implementations, it is intended that this parameter will be prepended to the phoneNumbers attribute sequence values, the deprecated telephone attribute MUST then be set to NULL and discarded.'

4. The Contact API has multiple defunct methods:
1. AddressBook.createContact(...) - why can't we just create a 'Contact' object as a literal object?

var newContact = { name: .... };

CR: Update 'Contact createContact([Optional] in ContactOptions options) raises(SecurityError, DeviceAPIError);' to '[Deprecated] Contact createContact([Optional] in ContactOptions options) raises(SecurityError, DeviceAPIError);'

2. Contact.setProperty(...) - why not just add the new parameter directly to the 'Contact' object literal?

newContact.prototype.newProp = 'something';

CR: Update 'void setProperty(in DOMString propertyName, in Object propertyValue) raises(DeviceAPIError);' to '[Deprecated] void setProperty(in DOMString propertyName, in Object propertyValue) raises(DeviceAPIError);'

3. Contact.getProperty(...) - why not just retrieve the parameter directly from the 'Contact' object literal?

alert(newContact.newProp);

CR: Update 'Object getProperty(in DOMString propertyName) raises(DeviceAPIError);' to '[Deprecated] Object getProperty(in DOMString propertyName) raises(DeviceAPIError);'

4. Contact.getSupportedPropertyKeys(...) - why not just enumerate over the attributes of the current 'Contact' object?

for(var propertyName in newContact) {
   alert(propertyName + ": " + newContact[propertyName]);
}

CR: Update 'StringArray getSupportedPropertyKeys();' to '[Deprecated] StringArray getSupportedPropertyKeys();'

5. Contact.id must be marked as 'readonly' in the WebIDL fragment. It is described as read only in the description (which I agree is correct).

CR: Update 'attribute DOMString id;' to 'readonly attribute DOMString id;'

6. Most contacts have more than one email address (e.g. home and work). Being able to store more than one email address could be useful.

CR:
- Update 'attribute DOMString email;' to '[Deprecated] attribute DOMString email;'
- Add 'attribute sequence<DOMString> emails;'
- Add the following clause in descriptive text: 'When the deprecated email attribute is used by implementations, it is intended that this parameter will be prepended to the emails attribute sequence values, the deprecated email attribute MUST then be set to NULL and discarded.'.

7. Most contacts have more than one address (e.g. home and work). Multiple addresses for each contact could be useful.

CR:
- Update 'attribute Address address;' to '[Deprecated] attribute Address address;'
- Add 'attribute sequence<Address> addresses;'
- Add the following clause in descriptive text: 'When the deprecated address attribute is used by implementations, it is intended that this parameter will be prepended to the addresses attribute sequence values, the deprecated address attribute MUST then be set to NULL and discarded.'.

8. Most contacts may have more than one nickname, especially if this field is used to store Instant Messaging handles for users (e.g. IRC, AIM, Jabber, etc).

CR:
- Update 'attribute DOMString nickname;' to '[Deprecated] attribute DOMString nickname;'
- Add 'attribute sequence<DOMString> nicknames;'
- Add the following clause in descriptive text: 'When the deprecated nickname attribute is used by implementations, it is intended that this parameter will be prepended to the nicknames attribute sequence values, the deprecated nickname attribute MUST then be set to NULL and discarded.'.

9. Multiple 'street' atributes in the Address object could be useful.

CR:
- Update 'attribute DOMString street;' to '[Deprecated] attribute DOMString street;'
- Add 'attribute sequence<DOMString> streets;'
- Add the following clause in descriptive text: 'When the deprecated street attribute is used by implementations, it is intended that this parameter will be prepended to the streets attribute sequence values, the deprecated street attribute MUST then be set to NULL and discarded.'.

10. What is the basis for the Contact interface attributes? Perhaps we should look towards a suitable Contact information standard?

CR: See CR21 (below).

11. Contact Searching and Filtering is largely ineffective:

- ContactFilter is not rigourously defined. Are multiple items contained within a ContactFilter object additive (i.e. match attribute1 AND attribute2, etc) or will any matches on any attributes return results (i.e. match attribute1 OR attribute2 OR attribute3 etc)?

CR: Add the following clause to Section 3.8: 'All attributes that are set within a single ContactFilter object represet logical 'AND' unions (i.e. only Contact objects will be returned that match ALL attributes provided in a single ContactFilter object).'

- When searching for contacts, no sorting or pagination options are provided for the results
- if the Contacts address book is large the application could be waiting for a long time for a lot of results to return in one go.

CR: Add contact options to the API. TBD exactly how to do this but perhaps suited to the next BONDI version. That is not related to the current ContactOptions interface (see next 2 comments). TBD.

12. ContactOptions seems to be bad naming. This interface is not related to any options per se. Essentially it is a copy of the Contact object (see next point)

CR: Remove ContactOptions from API. This interface is not included in v1.01 so no backward compatibility issues with this change.

13. Why does ContactOptions exist? When creating a new Contact object why don't we just create a new literal Contact object?

var newContact = { name: .... };

CR: Remove ContactOptions from API. This interface is not included in v1.01 so no backward compatibility issues with this change.

14. AddressBook.deleteAllContacts(...) seems a.) unnecessary and b.) dangerous. If I want to delete all contacts I should run an iterative loop over the deleteContact(...) method. The use case for deleting all contacts is niche (at best). It perhaps does not warrant it's own method in the API(?)

CR: Update 'PendingOperation deleteAllContacts(in SuccessCallback successCallback, in ErrorCallback errorCallback);' to '[Deprecated] PendingOperation deleteAllContacts(in SuccessCallback successCallback, in ErrorCallback errorCallback);'

15. No examples are provided in the API for Contact.id attribute. It is an important attribute and it may make sense to provide some guidelines to implementors about how they should identify Contact objects so that the identifiers do not overlap and that they are unique. Perhaps some guidelines for implementors could be provided around RFC4122?

CR:
- Add guidelines for implementors on how to set universally unique Contact id attributes as defined in RFC4122.
- Remove existing code example.
- Add the following example code to Contact.id: '{ id: 'urn:uuid:d13d4fd0-4ce9-1cef-b1f2-10a9c1446bf0' }'.

16. Code example for Contact.phoneNumbers and Section 3.6 is still marked as 'todo'. Examples for these objects should be provided.

CR: Add code example(s) to Section 3.4 AND Section 3.6 'phoneNumbers' attribute.

17. Contact.photo (or at least the example code provided) does not make any sense in its present form. What is the leading slash meant to attach to? Where does the photo actually reside (on the device? network? web?) ? What is the naming system in use for this attribute (i.e. URI?) and is the root directory object defined? If the root directory object is defined, where is it defined?

CR: Thoroughly define the format and purpose of this attribute to avoid conflicting interpretations of its use (TBD).

18. No classification is provided for email addresses or addresses. i.e. what do the address or email address provided mean / point to? Are they 'home' or 'work' addresses? Are the domestic or international address? Are they the user's preferred email address or address? Are the addresses associated with any other uses? This IS supported to a limited degree for phone numbers (see next point).

CR:
- Create a new EmailAddress object and add 'attribute sequence<DOMString> types;' and 'attribute DOMString email;' to this object. Redefine from CR6 (above) 'attribute sequence<DOMString> emails;' to 'attribute sequence<EmailAddress> emails;'.
- Add 'attribute sequence<DOMString> types;' to Address object in Section 3.5.

19. A Contact may have more types of phone number than the constants defined in the ContactManager interface. So far we have defined mobile, landline, fax, work and home. I can suggest a few more should also be defined: msg, pager, video, bbs, modem, car, isdn, pcs. Some of those may actually be defunct but the point is that we don't have any flexibility in the types of phone number that we can specify in the API.

CR:
- Update AddressBook object from:

const unsigned short MOBILE_NUMBER  = 0;
const unsigned short LANDLINE_NUMBER  = 1;
const unsigned short FAX_NUMBER  = 2;
const unsigned short WORK_NUMBER  = 3;
const unsigned short HOME_NUMBER  = 4;

to:

[Deprecated] const unsigned short MOBILE_NUMBER  = 0;
[Deprecated] const unsigned short LANDLINE_NUMBER  = 1;
[Deprecated] const unsigned short FAX_NUMBER  = 2;
[Deprecated] const unsigned short WORK_NUMBER  = 3;
[Deprecated] const unsigned short HOME_NUMBER  = 4;

- Update PhoneNumber object (section 3.6) 'attribute unsigned short type;' to '[Deprecated] attribute unsigned short type;'
- Update PhoneNumber object (section 3.6) 'attribute unsigned short subtype;' to '[Deprecated] attribute unsigned short subtype;'
- Add 'attribute sequence<DOMString> types;' to PhoneNumber object (section 3.6).

20. Provision should be made in the Contact API for extended attributes. We should include a note to express that additional attributes that haven't been defined can be added but their naming should be prepended with an 'x' (i.e. xProp, xJabber). Preferably these attributes would be in the form 'x-' as per the e.g. vCard standards.

CR: Add descriptive text to this effect in Section 3.4.

21. What is the basis for the selection of Contact interface attributes? The list is particularly limited. It would perhaps be more suitable to conform with an industry-wide format for Contact details i.e. vCard, Portable Contacts, hCard, OpenSocial, etc). Contact attributes available should be scoped further based on implementation support.

CR: Implement a more advanced set of Contact attributes based on an existing standard i.e. vCard, Portable Contacts, hCard, OpenSocial, etc (TBD).

22. Contact.additionalInformation seems badly scoped and defined. It is relatively easy to say that anything not supported by the (very limited) Contact attributes can be put in to this additionalInformation attribute but the structure of that data is completely lost. Any data such as 'a floor number in a building, an apartment number, the name of an office occupant, etc' in this field is particularly useless. It would be less useless if the format of how these attributes could be stored in this field was defined but it may just be better to remove this reference. additionalInformation is useful (I'd prefer if we called it 'notes') but it must be clear that the data it will contain will be unstructured and the meaning of any data included in this attribute will be lost. it does not imply that data can be dumped and then restored across other implementations, at least not in its present form.

23. What happens when PendingOperation.cancel() fails for any reason? I will assume that a PENDING_OPERATION_ERROR (as defined in the bondi module) will be thrown via the method's ErrorCallback function? This should be clearly defined, though perhaps this can be defined further in the bondi module to cover this use case across all other APIs as well.

24. If ContactManager.getAddressBooks(...) raises a SecurityError (as per the API) then it MUST be asynchronous. A synchronous method raising any errors is automatically a potentially blocking process. Blocking processes impede the user and degrade the user experience of the application. This method MUST be asynchronous, or, perhaps preferably, the SecurityError should be deprecated.

25. No concept is included of a 'preferred' phone number, email address or address. Usually a preferred address can be expressed and is used as the default for communication purposes.

26. In the AddressBook interface all methods are shown to 'raise(SecurityError, DeviceAPIError)'. I suggest that these errors are pushed through the ErrorCallback function and caught asynchronously. So the references to raises(...) should be removed?

27. Why is ErrorCallback not an optional attribute? I don't see why I can't just ignore any errors that occur. There may be a good case for ErrorCallback not being optional...but as a developer less is definitely more.

28. Just an API sanity check. Is the ContactArraySuccessCallback parameter optional? i.e. If no Contact matches are found and no results can be returned is an ErrorCallback triggered with a DeviceAPIError object with a NOT_FOUND_ERROR error? Or, does the SuccessCalback get returned with a null response? I'm not completely clear on this and would just like to clarify (and also have something to this effect in the API documentation perhaps).

29. It could be good to be more descriptive on the cases in which errors are thrown from each of the methods in Contacts API. For example, 'if no matching Contacts are found in the AddressBook and ErrorCallback MUST be triggered with a DeviceAPIError payload. The error code returned in this case would be a DeviceAPIError.NOT_FOUND_ERROR.' ...something like that could be useful and wide ranging implications for consistent implementations of the API.

Fix backward compatibility break.

Resolve ambiguity in the API specification regarding error handling, examples, Contact attributes.

Sanity check different parts of the Contacts API. Sanity check general BONDI design patterns.

I think that the identifiers of the parameters (inContacts, knownName etc) of the device capabilities could be all made lower-case.
Additionally the processing specified in A&S Appendices could accept all the identifiers (not only parameters, but really all of them) case-insensitively, however, I do not have strong opinion on this.

Avoidance of potential errors in usage

http://bondi.omtp.org/1.1/cr/apis/applauncher.html
1.3. Device capabilities
The description of the security parameter "path: allow or deny to launch a given application path " is confusing.

Change to "path on the filesystem, e.g. for limiting filesystem locations from which applications can be launched"

http://bondi.omtp.org/1.1/cr/apis/messaging.html
createMMS
Fix "INVALID_ARGUMENT_ERROR if smsParams is not a valid MMSOptions object "

Typo

SMS/MMS/Email subscriptions should persist (or at least optionally persist, upon request of the widget) when a widget exits, i.e. when the subscribed event occurs, the widget is started and the event is delivered.
Note this is assumed not to be supported for browser webapps, i.e. their subscriptions should be valid only when the webapp is running.

Subscription persistence is important to avoid that widgets must always be running, e.g. if they expect only to intermittently receive events via SMS/MMS/email. Some platforms will not support widgets to be running in the background, e.g. they may support only a single running application or a limited set of special/core applications.

http://bondi.omtp.org/1.1/cr/apis/messaging.html
appendAttachment
Support an optional parameter for MIME type of attachment to add.

In order to correctly set the multipart/mixed content section for the attachment, the email client needs to know the MIME type of the attachment.

1. In the document "BONDI_Interface_Patterns_v1.1.html", there is a
sentence which reads, "It shall be clearly stated where an object that instantiates an interface, i.e. property of which object it becomes."
What is meant by this sentence?  It appears there is a grammatical error which is hampering its clarity.

AT&T CR

1. In the document "BONDI_Interface_Patterns_v1.1.html", in the section "3.2. API coverage by features", the word
"sensitive" does not make sense in this context.  Perhaps you meant "affected".  In that case, you would also need a comma after the word "affected" in order to maintain clarity.  Also, the word "API" should be changed to "APIs" in this paragraph. 

AT&T CR

We have just TakePicture API, in earlier BONDI 1.01 we had startviewfinder API, how this will be taken care in BONDI 1.1

Please let us know how  to havdle this StartViewfinder in BONDI 1.1 ?

BONDI 1.1
Module : Telephony

Example:
bondi.telephonyLog.findLogEntries
(successCallback,
errorCallback,
callsArray,
{phoneNumber:"+34666666666"} );

In LogManager interface the findLogEntries() API contains a argument Logfilter which is map.

The map contains properties as key, value paris.
In example give in the specs, only "phoneNumber" is the call property specified as LogFilter which is a map.

Are there any other properties like duration, startTime etc for the LogFilter ?