Prev: Module agenda: Agenda Database
Module contacts: Contacts Database
This module allows to read and manipulate the contacts stored on the phone.
In the phone's database, a contact is identified by its id, an integer number.
Contact Fields
In m, a contact is represented as an array whose elements are the fields of the contact. Fields are identified by their (array) keys. m recognizes the following keys, with the corresponding data type:
| Key | Meaning |
| adr | Address (street) |
| birth | Birthday |
| cell | Cellphone number |
| company | Company name |
| country | Country |
| email | e-mail address |
| extadr | Additional address |
| extname | Additional name |
| fax | Fax number |
| fname | First name |
| loc | Locality (city) |
| name | (Family) name |
| |
| Key | Meaning |
| note | Contact note |
| pager | Pager number |
| phone | Voice phone number |
| pict | Picture image data |
| po | Post Office |
| region | Region |
| ring | Ringtone file name |
| text | Free text |
| title | Job Title |
| url | Website URL |
| video | Video phone number |
| zip | Post Code |
| |
| |
Key names are not case sensitive.
The order of fields in the array describing a contact is arbitrary. Arrays returned by functions in this module always start with the two fields name and fname, if these fields exist.
Address and phone number fields can have one of the following suffices:
| Suffix | Meaning |
| .home | Home address or phone |
| .work | Work address or phone |
| |
For instance, phone.home refers to the home phone number, phone.work to the work phone number. phone without suffix is unspecified.
Most fields are represented as strings. There are two exceptions:
- birth: The birthday is stored as a number indicating the seconds since year zero. This is the format used by module time.
- pict: The picture is stored as an array containing the image data, typically in JPEG format. Example functions to load or store a the picture of a contact c:
use io
function loadpict(file, c)
f=io.open(file);
s=io.read(f, io.size(f)); // read whole file
io.close(f);
c["pict"]=code(s) // string to byte array
end
function storepict(c, file)
if c["pict"]#null then
s=char(c["pict"]); // byte array to string
f=io.create(file);
io.write(f, s);
io.close(f)
end
end
|
Note that the builtin contacts application in the phone may not support all keys, or display some of them in a strange way. Furthermore, not all applications clearly separate home from work data. Hence, the cell phone number of a person is sometimes stored as
cell, sometimes as
cell.work or as
cell.home.
The functions of this module throw ExcInvalidParam if a contact array has no keys, or ErrBadName if a contact array has a key which is not in the above table.
contacts.add
• function add(contact) → Number
Permissions: WriteApp
Add a contact to the database, and return its id. The contact must be an array with keys from the above tables.
c=["name": "Shakespeare",
"fname": "William",
"loc.home": "Stratford-upon-Avon"],
"loc.work": "London",
"birth": time.num("1564-04-23")];
contacts.add(c)
→ 114
|
contacts.delete
• function delete(id) → null
Permissions: WriteApp
Delete the contact with the given id.
Throws ErrNotFound if there is no such contact.
// delete the contact added in the add example
contacts.delete(114)
|
contacts.find
• function find(text=null, keys=["name","fname"], sort=[]) → Array
Permissions: ReadApp
Searches the contact database for entries matching text considering the fields specified in keys, and returns the ids of the matching contacts sorted by the fields specified in sort:
- If text=null, all entries are returned, and keys is ignored.
- If text#null, searches the contact database for all entries matching the words in text when considering the fields defined by keys. Both text and all fields from the database are split into words (sequences of characters or digits) before comparing them. An entry matches if all of the words in text are found in any of the fields considered. Words can also be abbreviated: William matches both W or Will in the search text.
If keys defines a single field, it can be a string, otherwise it must be an array of strings.
- If sort=[], the ids are sorted by their ascending numeric value.
- If sort is a string, the ids are sorted by the corresponding field.
- If sort is an array, the ids are sorted by the corresponding fields, from highest to lowest sort order.
Throws
ErrArgument if there are more than 32 keys or sort keys specified.
// get the number of contacts in the database
print len(contacts.find())
→ 104
// print these contacts, sorted by name and first name
for id in contacts.find(null,null,["name", "fname"]) do
c=contacts.get(id);
print c[1], c[0]
end
→ ...
William Shakespeare
...
// Will matches William; so does W
print contacts.find("Will Shakespeare")
→ [114]
print contacts.find("W. Shakespeare")
→ [114]
// get the ids of everybody living or working in London
print contacts.find("London", "loc")
→ [45,67,89,90,91,114]
// Stratford-upon-Avon is considered three words,
// so Avon matches
print contacts.find("Avon", "loc")
→ [114]
|
contacts.findnr
• function findnr(number, digits=8) → Array
Permissions: ReadApp
Retrieves the ids of the entries matching the given phone number. Only the last digits digits in number are considered when comparing. The minimum for digits is 7.
This function is much faster than find, and more useful, as it only looks at digits, and the end of the phone numbers.
Throws ExcValueOutOfRange if digits is out of range.
print contacts.findnr("+41(079)7654321", 9)
→ [28]
|
contacts.get
• function get(id, keys=null) → Array
Permissions: ReadApp
Get fields of the contact with id id. If keys=null, returns all fields defined for the contact. If keys#null, returns only the fields specified in keys. keys can be a single string specifying a single field, or an array specifying multiple fields.
If they exist, the fields name and/or fname are at the beginning of the returned array.
Throws ErrNotFound if there is no contact with this id; throws ErrArgument if there are more than 32 keys specified.
c=contacts.get(114);
print c
→ [Shakespeare,William,Stratford-upon-Avon,London,
49365849600]
print time.str(c["birth"])
→ 1564-04-23 00:00:00
print contacts.get(114, ["name", "fname"])
→ [Shakespeare,William]
c=contacts.get(114, "loc");
print c
→ [Stratford-upon-Avon,London]
print keys(c)
→ [loc.home,loc.work]
|
contacts.labels
• function labels(keys=null) → Array
Get labels for the fields. Labels are language dependent. keys is interpreted as follows:
- If keys=null, returns all standard labels.
- If keys is a string, returns the label(s) for the corresponding field(s).
- If keys is an array, returns the labels for the corresponding fields.
Throws
ErrArgument if there are more than 32 keys specified.
Suffices (.home, .work) can be used as keys, but not as field suffices: labels() throws ErrBadName in this case.
If they exist, the labels for name and/or fname are at the beginning of the returned array.
The label array has the same keys as a contact.
l=contacts.labels();
print l
→ [Last name,First name,Tel. (home),Mobile
(home),Fax (home),E-mail (home),Web addr. (home),
Street (home),...<46>]
l["title"]
→ Job title
// print a contact with all its labels
c=contacts.get(114);
for k in keys(c) do
print l[k], "-", c[k]
end
→ Last name - Shakespeare
First name - William
City (home) - Stratford-upon-Avon
City (business) - London
Birthday - 49365849600
// get all work related labels
print contacts.labels([".work"])
→ [Tel. (business),Mobile (business),Fax
(business),E-mail (business),Web addr. (bus.),Street
(business),...<12>]
contacts.labels("phone.work")
→ ErrBadName thrown
|
contacts.new
• function new(time) → Array
Permissions: ReadApp
Returns the list of contacts modified since the specified point in time. time is the number of seconds since year 0 UTC. See also module time.
// get the entries changed within the last ten minutes
print contacts.new(time.utc()-10*60)
→ [114]
|
contacts.own
• function own() → Number
Permissions: ReadApp
• function own(id) → Number
Permissions: ReadApp+WriteApp
There is a single contact in the database which can be marked as own contact, indicating the owner of the phone (or any other particular person). Some phones can use this information to quickly send a vCard[11] of the phone owner.
Without an argument, the id of this contact is returned. With an argument, the own contact id is set to id, and the old one is returned.
Returns -1 if no own contact has been set, or it has been deleted.
Throws ErrNotFound if there is no contact with this id.
// if there is no owner, make it the first Shakespeare
if contacts.own()=-1 then
ids=contacts.find("Shakespeare");
if len(ids)>0 then
contacts.own(ids[0])
end
end
|
contacts.set
• function set(id, contact) → null
Permissions: WriteApp
Updates the contact with id id, updating or adding fields in array contact. contact must be an array with keys from the above tables.
Fields already existing in the database are updated, the other fields are added. Fields not in the array are not modified. Fields which are null in the array are removed from the contact.
// Replace all +41 1 numbers by +41 44
const fields=["phone", "fax", "cell", "pager"]);
for id in contacts.find() do
c=contacts.get(id, fields);
m=false;
for i=0 to len(c)-1 do
// field could be null or too short
if c[i]!=null then
n=trim(c[i]);
if len(n)>=11 then
// replace +411 by +4144
if substr(n,0,4)="+411" then
c[i]="+4144" + substr(n, 4); m=true
// replace +41 1 by +41 44
elsif substr(n,0,5)="+41 1" then
c[i]="+41 44" + substr(n, 5); m=true
end
end
end
end;
if m then
contacts.set(id, c)
end
end
|
Next: Communications© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
