Skip to content
Browse files

Adopt the ContactsWriter API for manipulating contacts. Document PoCo…

…-inspired search options.
  • Loading branch information...
1 parent 7016d66 commit b461e8b7e895b18a8341d5c126649de034c3f61f @philikon committed Nov 18, 2011
Showing with 112 additions and 46 deletions.
  1. +97 −16 idl/api.idl
  2. +15 −30 idl/schema.idl
View
113 idl/api.idl
@@ -1,30 +1,55 @@
/**
- * XXX TODO
+ * This is the read-only portion API of the navigator.contacts object.
*/
[NoInterfaceObject]
interface Contacts {
- void create(ContactSuccessCB successCb,
- ContactErrorCB errorCb,
- Contact contact);
- void update(ContactSuccessCB successCb,
- ContactErrorCB errorCb,
- Contact contact);
- void delete(ContactSuccessCB successCb,
- ContactErrorCB errorCb,
- Contact contact);
void find(ContactFindCB successCb,
ContactErrorCB errorCb,
ContactFindOptions options);
};
+/**
+ * (Taken verbatim from ContactsWriter draft)
+ */
+[NoInterfaceObject]
+interface ContactsWriter : Contacts {
+ Contact create(ContactProperties properties);
+};
+
+/**
+ * (Taken verbatim from ContactsWriter draft)
+ */
+[NoInterfaceObject]
+interface ContactWriter : ContactProperties {
+ void save(ContactSuccessCB successCb,
+ ContactErrorCB errorCb);
+ void remove(ContactSuccessCB successCb,
+ ContactErrorCB errorCb);
+ Contact clone();
+};
+
+/**
+ * A Contact object combines the fields from ContactProperties and the methods
+ * from ContactWriter. On top of that it contains read-only attributes set by
+ * the database.
+ */
+[NoInterfaceObject]
+interface Contact : ContactWriter {
+ readonly attribute DOMString id;
+
+ readonly attribute Date? published;
+ readonly attribute Date? updated;
+};
+
+/**
+ * (Taken verbatim from ContactsWriter draft)
+ */
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactSuccessCB {
- void onsuccess(in DOMString id);
+ void onsuccess (Contact contact);
};
/**
- * XXX TODO
- *
* (Taken verbatim from W3C Editor's Draft 10 November 2011)
*/
[Callback=FunctionOnly, NoInterfaceObject]
@@ -33,8 +58,6 @@ interface ContactErrorCB {
};
/**
- * XXX TODO
- *
* (Taken verbatim from W3C Editor's Draft 10 November 2011)
*/
[NoInterfaceObject]
@@ -50,7 +73,7 @@ interface ContactError {
};
/**
- * XXX TODO
+ * Object specifying search options.
*
* Based on the Portable Contacts query API
* (http://portablecontacts.net/draft-spec.html). The only difference is
@@ -61,19 +84,77 @@ interface ContactError {
[NoInterfaceObject]
interface ContactFindOptions {
/* presentation */
+
+ /**
+ * Search qualifier.
+ *
+ * The W3C draft requires this to have non-zero length, which means one
+ * must always explicitly state the fields which can be pretty tedious.
+ * Although analogous to SQL's SELECT, one could define "*" matching all
+ * possible fields.
+ */
attribute DOMString[]? fields;
/* filtering */
+
+ /**
+ * List of one or more field names that 'filterOp' and 'filterValue' are
+ * applied to. If this is provided, at least 'filterOp' must be provided
+ * too. A record matches when the filter matches at least one of the
+ * specified fields' values.
+ */
attribute DOMString[]? filterBy;
+
+ /**
+ * Filter operation to perform. Valid operations are
+ * - 'present': the field value must be non-empty.
+ * - 'equals': the field value must be identical to the 'filterValue'.
+ * - 'contains': 'filterValue' must be a substring of the field value.
+ * - 'startswith': 'filterValue' must be a substring of the field value,
+ * starting at the beginning.
+ * - 'iequals', 'icontains', 'istartswith' work like their respective
+ * equivalents, but they ignore case.
+ */
attribute DOMString? filterOp;
+
+ /**
+ * Value to filter by, using the comparison method specified by 'filterOp'.
+ */
attribute DOMString? filterValue;
+
+ /**
+ * Only return records that have been added or modified since this time.
+ */
attribute Date? updatedSince;
/* sorting */
+
+ /**
+ * List of one or more field names to sort records by. Records will first
+ * be sorted by the first field, then the second, and so forth. Sorting
+ * by plural fields will sort according to the entry marked primary.
+ */
attribute DOMString[]? sortBy;
+
+ /**
+ * Order in which the sorting is to be done. Valid values are
+ * - 'ascending' (default)
+ * - 'descending'
+ */
attribute DOMString? sortOrder;
/* pagination */
+
+ /**
+ * Specify the offset of the first result to be returned with respect
+ * to the total list of records matching the query. This must be non-
+ * negative and defaults to 0.
+ */
attribute long? startIndex;
+
+ /**
+ * Specified the number of records to be returned, if non-zero. Defaults
+ * to 0.
+ */
attribute long? count;
};
View
45 idl/schema.idl
@@ -1,41 +1,32 @@
/**
- * XXX TODO
+ * (This is similar to the W3C API and the PoCo definitions.)
*/
[NoInterfaceObject]
-interface Contact {
+interface ContactProperties {
/* singular fields */
- //XXX philikon: I don't think it's very useful to declare 'id' to be
- // readonly, unless we give contact syncing apps a way to associate
- // their upstream IDs with the contact as well and query by it.
- readonly attribute DOMString id;
- readonly attribute Date? published;
- readonly attribute Date? updated;
-
- attribute DOMString? displayName;
- attribute ContactName? name;
- attribute DOMString? nickname;
- attribute DOMString? note;
- attribute Date? birthday;
+ attribute DOMString? displayName;
+ attribute ContactName? name;
+ attribute DOMString? nickname;
+ attribute DOMString? note;
+ attribute Date? birthday;
/* plural fields */
- attribute ContactField[]? emails;
- attribute ContactField[]? urls;
- attribute ContactField[]? phoneNumbers;
- attribute ContactField[]? ims;
- attribute ContactField[]? photos;
- attribute ContactAddress[]? addresses;
- attribute ContactOrganization[]? organizations;
- attribute DOMString[]? categories; // PoCo calls these tags?
+ attribute ContactField[]? emails;
+ attribute ContactField[]? urls;
+ attribute ContactField[]? phoneNumbers;
+ attribute ContactField[]? ims;
+ attribute ContactField[]? photos;
+ attribute ContactAddress[]? addresses;
+ attribute ContactOrganization[]? organizations;
+ attribute DOMString[]? categories; // PoCo calls these tags?
//TODO additional PoCo fields?
};
/**
- * XXX TODO
- *
* (This is similar to the W3C API, though it also includes the 'formatted'
* field as defined by PoCo and allows multiple values for name segments
* as defined by vCard4.)
@@ -51,8 +42,6 @@ interface ContactName {
};
/**
- * XXX TODO
- *
* (This is similar to the W3C API, though it uses 'primary' instead of
* 'pref'.)
*/
@@ -65,8 +54,6 @@ interface ContactField {
/**
- * XXX TODO
- *
* (This is similar to the W3C API, though it uses 'primary' instead of
* 'pref' and adds the 'formatted' attribute as defined by PoCo.)
*/
@@ -83,8 +70,6 @@ interface ContactAddress {
};
/**
- * XXX TODO
- *
* (This is similar to the W3C API, though it uses 'primary' instead of
* 'pref' and XXX TODO.)
*/

0 comments on commit b461e8b

Please sign in to comment.
Something went wrong with that request. Please try again.