public/cordova-android
public/cordova-android
9
0
Fork 0
forked from github/cordova-android
Code Pull Requests Activity

Adding comments to Contact code

Browse Source
This commit is contained in:
macdonst 2010-10-19 04:05:36 +08:00
parent bc086cb93d
commit 9cd4d4c603
4 changed files with 290 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
framework/assets/js/contact.js
View File

@ -1,4 +1,37 @@
/**
* PhoneGap is available under *either* the terms of the modified BSD license *or* the
* MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
*
* Copyright (c) 2005-2010, Nitobi
* Copyright (c) 2010, IBM Corporation
*/
/**
* Contains information about a single contact.
* @param {DOMString} id unique identifier
* @param {DOMString} displayName
* @param {ContactName} name
* @param {DOMString} nickname
* @param {ContactField[]} phoneNumbers array of phone numbers
* @param {ContactField[]} emails array of email addresses
* @param {ContactAddress[]} addresses array of addresses
* @param {ContactField[]} ims instant messaging user ids
* @param {ContactOrganization[]} organizations
* @param {DOMString} published date contact was first created
* @param {DOMString} updated date contact was last updated
* @param {DOMString} birthday contact's birthday
* @param (DOMString} anniversary contact's anniversary
* @param {DOMString} gender contact's gender
* @param {DOMString} note user notes about contact
* @param {DOMString} preferredUsername
* @param {ContactField[]} photos
* @param {ContactField[]} tags
* @param {ContactField[]} relationships
* @param {ContactField[]} urls contact's web sites
* @param {ContactAccounts[]} accounts contact's online accounts
* @param {DOMString} utcOffset UTC time zone offset
* @param {DOMString} connected
*/
var Contact = function(id, displayName, name, nickname, phoneNumbers, emails, addresses,
ims, organizations, published, updated, birthday, anniversary, gender, note,
preferredUsername, photos, tags, relationships, urls, accounts, utcOffset, connected) {
@ -27,7 +60,11 @@ var Contact = function(id, displayName, name, nickname, phoneNumbers, emails, ad
this.connected = connected || null;
};
/**
* Removes contact from device storage.
* @param successCB success callback
* @param errorCB error callback
*/
Contact.prototype.remove = function(successCB, errorCB) {
if (this.id == null) {
var errorObj = new ContactError();
@ -38,16 +75,34 @@ Contact.prototype.remove = function(successCB, errorCB) {
PhoneGap.execAsync(successCB, errorCB, "Contacts", "remove", [this.id]);
};
/**
* Creates a deep copy of this Contact.
* With the contact ID set to null.
* @return copy of this Contact
*/
Contact.prototype.clone = function() {
var clonedContact = PhoneGap.clone(this);
clonedContact.id = null;
return clonedContact;
};
Contact.prototype.save = function(win, fail) {
/**
* Persists contact to device storage.
* @param successCB success callback
* @param errorCB error callback
*/
Contact.prototype.save = function(successCB, errorCB) {
};
/**
* Contact name.
* @param formatted
* @param familyName
* @param givenName
* @param middle
* @param prefix
* @param suffix
*/
var ContactName = function(formatted, familyName, givenName, middle, prefix, suffix) {
this.formatted = formatted || null;
this.familyName = familyName || null;
@ -57,12 +112,27 @@ var ContactName = function(formatted, familyName, givenName, middle, prefix, suf
this.honorificSuffix = suffix || null;
};
/**
* Generic contact field.
* @param type
* @param value
* @param primary
*/
var ContactField = function(type, value, primary) {
this.type = type || null;
this.value = value || null;
this.primary = primary || null;
};
/**
* Contact address.
* @param formatted
* @param streetAddress
* @param locality
* @param region
* @param postalCode
* @param country
*/
var ContactAddress = function(formatted, streetAddress, locality, region, postalCode, country) {
this.formatted = formatted || null;
this.streetAddress = streetAddress || null;
@ -72,6 +142,16 @@ var ContactAddress = function(formatted, streetAddress, locality, region, postal
this.country = country || null;
};
/**
* Contact organization.
* @param name
* @param dept
* @param title
* @param startDate
* @param endDate
* @param location
* @param desc
*/
var ContactOrganization = function(name, dept, title, startDate, endDate, location, desc) {
this.name = name || null;
this.department = dept || null;
@ -82,23 +162,44 @@ var ContactOrganization = function(name, dept, title, startDate, endDate, locati
this.description = desc || null;
};
/**
* Contact account.
* @param domain
* @param username
* @param userid
*/
var ContactAccount = function(domain, username, userid) {
this.domain = domain || null;
this.username = username || null;
this.userid = userid || null;
}
/**
* Represents a group of Contacts.
*/
var Contacts = function() {
this.inProgress = false;
this.records = new Array();
}
Contacts.prototype.find = function(fields, win, fail, options) {
/**
* Returns an array of Contacts matching the search criteria.
* @param fields that should be searched
* @param successCB success callback
* @param errorCB error callback
* @param {ContactFindOptions} options that can be applied to contact searching
* @return array of Contacts matching search criteria
*/
Contacts.prototype.find = function(fields, successCB, errorCB, options) {
PhoneGap.execAsync(win, fail, "Contacts", "search", [fields, options]);
};
//This function does not create a new contact in the db.
//Must call contact.save() for it to be persisted in the db.
/**
* This function creates a new contact, but it does not persist the contact
* to device storage. To persist the contact to device storage, invoke
* contact.save().
* @param properties an object who's properties will be examined to create a new Contact
* @returns new Contact object
*/
Contacts.prototype.create = function(properties) {
var contact = new Contact();
for (i in properties) {
@ -109,6 +210,13 @@ Contacts.prototype.create = function(properties) {
return contact;
};
/**
* ContactFindOptions.
* @param filter used to match contacts against
* @param multiple boolean used to determine if more than one contact should be returned
* @param limit maximum number of results to return from the contacts search
* @param updatedSince return only contact records that have been updated on or after the given time
*/
var ContactFindOptions = function(filter, multiple, limit, updatedSince) {
this.filter = filter || '';
this.multiple = multiple || false;
@ -116,10 +224,17 @@ var ContactFindOptions = function(filter, multiple, limit, updatedSince) {
this.updatedSince = updatedSince || '';
};
/**
* ContactError.
* An error code assigned by an implementation when an error has occurred
*/
var ContactError = function() {
this.code=null;
};
/**
* Error codes
*/
ContactError.UNKNOWN_ERROR = 0;
ContactError.INVALID_ARGUMENT_ERROR = 1;
ContactError.NOT_FOUND_ERROR = 2;
@ -129,6 +244,9 @@ ContactError.IO_ERROR = 5;
ContactError.NOT_SUPPORTED_ERROR = 6;
ContactError.PERMISSION_DENIED_ERROR = 20;
/**
* Add the contact interface into the browser.
*/
PhoneGap.addConstructor(function() {
if(typeof navigator.service == "undefined") navigator.service = new Object();
if(typeof navigator.service.contacts == "undefined") navigator.service.contacts = new Contacts();

21
framework/src/com/phonegap/ContactAccessor.java
View File

@ -86,18 +86,30 @@ public abstract class ContactAccessor {
return sInstance;
}
/**
* Check to see if the data associated with the key is required to
* be populated in the Contact object.
* @param key
* @param map created by running buildPopulationSet.
* @return true if the key data is required
*/
protected boolean isRequired(String key, HashMap<String,Boolean> map) {
Boolean retVal = map.get(key);
return (retVal == null) ? false : retVal.booleanValue();
}
protected HashMap<String,Boolean> buildPopulationSet(JSONArray filter) {
/**
* Create a hash map of what data needs to be populated in the Contact object
* @param fields the list of fields to populate
* @return the hash map of required data
*/
protected HashMap<String,Boolean> buildPopulationSet(JSONArray fields) {
HashMap<String,Boolean> map = new HashMap<String,Boolean>();
String key;
try {
for (int i=0; i<filter.length(); i++) {
key = filter.getString(i);
for (int i=0; i<fields.length(); i++) {
key = fields.getString(i);
if (key.startsWith("displayName")) {
map.put("displayName", true);
}
@ -160,6 +172,9 @@ public abstract class ContactAccessor {
*/
public abstract boolean remove(String id);
/**
* A class that represents the where clause to be used in the database query
*/
class WhereOptions {
private String where;
private String[] whereArgs;

75
framework/src/com/phonegap/ContactAccessorSdk3_4.java
View File

@ -55,6 +55,9 @@ import android.webkit.WebView;
*/
@SuppressWarnings("deprecation")
public class ContactAccessorSdk3_4 extends ContactAccessor {
/**
* A static map that converts the JavaScript property name to Android database column name.
*/
private static final Map<String, String> dbMap = new HashMap<String, String>();
static {
dbMap.put("id", People._ID);
@ -73,6 +76,9 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
dbMap.put("note", People.NOTES);
}
/**
* Create an contact accessor.
*/
public ContactAccessorSdk3_4(WebView view, Activity app)
{
mApp = app;
@ -80,7 +86,14 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
}
@Override
public JSONArray search(JSONArray filter, JSONObject options) {
/**
* This method takes the fields required and search options in order to produce an
* array of contacts that matches the criteria provided.
* @param fields an array of items to be used as search criteria
* @param options that can be applied to contact searching
* @return an array of contacts
*/
public JSONArray search(JSONArray fields, JSONObject options) {
String searchTerm = "";
int limit = 1;
boolean multiple = false;
@ -102,8 +115,8 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
ContentResolver cr = mApp.getContentResolver();
Set<String> contactIds = buildSetOfContactIds(filter, searchTerm);
HashMap<String,Boolean> populate = buildPopulationSet(filter);
Set<String> contactIds = buildSetOfContactIds(fields, searchTerm);
HashMap<String,Boolean> populate = buildPopulationSet(fields);
Iterator<String> it = contactIds.iterator();
@ -162,13 +175,20 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return contacts;
}
private Set<String> buildSetOfContactIds(JSONArray filter, String searchTerm) {
/**
* Query the database using the search term to build up a list of contact ID's
* matching the search term
* @param fields
* @param searchTerm
* @return a set of contact ID's
*/
private Set<String> buildSetOfContactIds(JSONArray fields, String searchTerm) {
Set<String> contactIds = new HashSet<String>();
String key;
try {
for (int i=0; i<filter.length(); i++) {
key = filter.getString(i);
for (int i=0; i<fields.length(); i++) {
key = fields.getString(i);
if (key.startsWith("displayName")) {
doQuery(searchTerm, contactIds,
People.CONTENT_URI,
@ -235,6 +255,15 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return contactIds;
}
/**
* A convenience method so we don't duplicate code in doQuery
* @param searchTerm
* @param contactIds
* @param uri
* @param projection
* @param selection
* @param selectionArgs
*/
private void doQuery(String searchTerm, Set<String> contactIds,
Uri uri, String projection, String selection, String[] selectionArgs) {
ContentResolver cr = mApp.getContentResolver();
@ -252,6 +281,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
cursor.close();
}
/**
* Create a ContactField JSONArray
* @param cr database access object
* @param contactId the ID to search the database for
* @return a JSONArray representing a set of ContactFields
*/
private JSONArray imQuery(ContentResolver cr, String contactId) {
String imWhere = ContactMethods.PERSON_ID
+ " = ? AND " + ContactMethods.KIND + " = ?";
@ -277,6 +312,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return null;
}
/**
* Create a ContactOrganization JSONArray
* @param cr database access object
* @param contactId the ID to search the database for
* @return a JSONArray representing a set of ContactOrganization
*/
private JSONArray organizationQuery(ContentResolver cr, String contactId) {
String orgWhere = ContactMethods.PERSON_ID + " = ?";
String[] orgWhereParams = new String[]{contactId};
@ -302,6 +343,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return organizations;
}
/**
* Create a ContactAddress JSONArray
* @param cr database access object
* @param contactId the ID to search the database for
* @return a JSONArray representing a set of ContactAddress
*/
private JSONArray addressQuery(ContentResolver cr, String contactId) {
String addrWhere = ContactMethods.PERSON_ID
+ " = ? AND " + ContactMethods.KIND + " = ?";
@ -323,6 +370,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return addresses;
}
/**
* Create a ContactField JSONArray
* @param cr database access object
* @param contactId the ID to search the database for
* @return a JSONArray representing a set of ContactFields
*/
private JSONArray phoneQuery(ContentResolver cr, String contactId) {
Cursor cursor = cr.query(
Phones.CONTENT_URI,
@ -345,6 +398,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
return phones;
}
/**
* Create a ContactField JSONArray
* @param cr database access object
* @param contactId the ID to search the database for
* @return a JSONArray representing a set of ContactFields
*/
private JSONArray emailQuery(ContentResolver cr, String contactId) {
Cursor cursor = cr.query(
ContactMethods.CONTENT_EMAIL_URI,
@ -375,6 +434,10 @@ public class ContactAccessorSdk3_4 extends ContactAccessor {
}
@Override
/**
* This method will remove a Contact from the database based on ID.
* @param id the unique ID of the contact to remove
*/
public boolean remove(String id) {
int result = mApp.getContentResolver().delete(People.CONTENT_URI,
"people._id = ?",

81
framework/src/com/phonegap/ContactAccessorSdk5.java
View File

@ -51,6 +51,9 @@ import android.webkit.WebView;
*/
public class ContactAccessorSdk5 extends ContactAccessor {
/**
* A static map that converts the JavaScript property name to Android database column name.
*/
private static final Map<String, String> dbMap = new HashMap<String, String>();
static {
dbMap.put("id", ContactsContract.Contacts._ID);
@ -102,11 +105,21 @@ public class ContactAccessorSdk5 extends ContactAccessor {
//dbMap.put("connected", null);
}
/**
* Create an contact accessor.
*/
public ContactAccessorSdk5(WebView view, Activity app) {
mApp = app;
mView = view;
}
/**
* This method takes the fields required and search options in order to produce an
* array of contacts that matches the criteria provided.
* @param fields an array of items to be used as search criteria
* @param options that can be applied to contact searching
* @return an array of contacts
*/
@Override
public JSONArray search(JSONArray fields, JSONObject options) {
long totalEnd;
@ -271,6 +284,18 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return contacts;
}
/**
* Create a new contact using a JSONObject to hold all the data.
* @param contact
* @param organizations array of organizations
* @param addresses array of addresses
* @param phones array of phones
* @param emails array of emails
* @param ims array of instant messenger addresses
* @param websites array of websites
* @param relationships array of relationships
* @return
*/
private JSONObject populateContact(JSONObject contact, JSONArray organizations,
JSONArray addresses, JSONArray phones, JSONArray emails,
JSONArray ims, JSONArray websites, JSONArray relationships) {
@ -289,7 +314,13 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return contact;
}
private WhereOptions buildWhereClause(JSONArray filter, String searchTerm) {
/**
* Take the search criteria passed into the method and create a SQL WHERE clause.
* @param fields the properties to search against
* @param searchTerm the string to search for
* @return an object containing the selection and selection args
*/
private WhereOptions buildWhereClause(JSONArray fields, String searchTerm) {
ArrayList<String> where = new ArrayList<String>();
ArrayList<String> whereArgs = new ArrayList<String>();
@ -307,8 +338,8 @@ public class ContactAccessorSdk5 extends ContactAccessor {
String key;
try {
for (int i=0; i<filter.length(); i++) {
key = filter.getString(i);
for (int i=0; i<fields.length(); i++) {
key = fields.getString(i);
if (key.startsWith("displayName")) {
where.add("(" + dbMap.get(key) + " LIKE ? )");
@ -410,6 +441,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return options;
}
/**
* Create a ContactOrganization JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactOrganization
*/
private JSONObject organizationQuery(Cursor cursor) {
JSONObject organization = new JSONObject();
try {
@ -428,6 +464,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return organization;
}
/**
* Create a ContactAddress JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactAddress
*/
private JSONObject addressQuery(Cursor cursor) {
JSONObject address = new JSONObject();
try {
@ -443,6 +484,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return address;
}
/**
* Create a ContactName JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactName
*/
private JSONObject nameQuery(Cursor cursor) {
JSONObject contactName = new JSONObject();
try {
@ -472,6 +518,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return contactName;
}
/**
* Create a ContactField JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactField
*/
private JSONObject phoneQuery(Cursor cursor) {
JSONObject phoneNumber = new JSONObject();
try {
@ -487,6 +538,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return phoneNumber;
}
/**
* Create a ContactField JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactField
*/
private JSONObject emailQuery(Cursor cursor) {
JSONObject email = new JSONObject();
try {
@ -499,6 +555,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return email;
}
/**
* Create a ContactField JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactField
*/
private JSONObject imQuery(Cursor cursor) {
JSONObject im = new JSONObject();
try {
@ -511,6 +572,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return im;
}
/**
* Create a ContactField JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactField
*/
private JSONObject websiteQuery(Cursor cursor) {
JSONObject website = new JSONObject();
try {
@ -523,6 +589,11 @@ public class ContactAccessorSdk5 extends ContactAccessor {
return website;
}
/**
* Create a ContactField JSONObject
* @param cursor the current database row
* @return a JSONObject representing a ContactField
*/
private JSONObject relationshipQuery(Cursor cursor) {
JSONObject relationship = new JSONObject();
try {
@ -541,6 +612,10 @@ public class ContactAccessorSdk5 extends ContactAccessor {
}
@Override
/**
* This method will remove a Contact from the database based on ID.
* @param id the unique ID of the contact to remove
*/
public boolean remove(String id) {
int result = mApp.getContentResolver().delete(ContactsContract.Data.CONTENT_URI,
ContactsContract.Data.CONTACT_ID + " = ?",