Up one Level S60 Module Reference Contents Module Index Index
Previous: Up: 6.4 Contacts Next:


6.4.2 Add

Add is used to add a contact or contact group to a contacts database. If the contact or contact group already exists in the database, it is replaced with the new entry.

You can use this method to both add and edit contacts and contact groups. The data is added to the specified database. When no database is specified, the data is added to the default database. If the default database does not exist, Add creates a new database. This method can be called both in synchronous and asynchronous mode.

The following is an example for using Add:

Synchronous 

contacts_handle.call('Add', {'Type': u'Contact', 'Data':
            {'FirstName': {'Label': u'first name', 'Value': u'Daniel'},
             'LastName': {'Label': u'last name', 'Value': u'Craig'},
             'MobilePhoneGen': {'Label': u'mobile', 'Value': u'9008025211'},
             'EmailHome': {'Label': u'email', 'Value': u'dcraig@ford.com'}}})

The following table summarizes the specification of Add:

Interface IDataSource
Operation Adds contact/group to the specified/default contacts database.
Response Model Synchronous and asynchronous for Third Edition FP2 and Fifth Edition devices.
Synchronous for Third Edition and Third Edition FP1 devices.
Pre-condition IDataSource interface is loaded. For editing an existing contact/group, the specified Id must exist. You must use GetList to retrieve the Id for editing.
Post-condition Adds a new contact item to the database in case of add and updates an existing contact in case of edit.

Input Parameters

Input parameter contains the contact information to add or edit and also the target database.

Table 6.65: Input parameters for Add
Name Type Range Description
Type unicode string Contact
Group		 Operation performed on the specified Type.
Data Contact (map) 6.66
Group (map)
[DBUri]: string
[id]: string
GroupLabel: string		 All string values in the map are unicode.
Key 1, Key 2, and so on are based on the keys supported.
id: For Type Contact, Id is the unique identifier for the contact to be modified.

id: for Type Group, Id is the unique identifier for the group to be modified.
GroupLabel: Label for the group being added or modified.

 Information about the contact/group to be added to the contacts database.

You must not set the Id/Id field to add a new entry and also, must not modify the value of the Id/Id field when editing an existing entry.

You must use the id that is given to it by GetList sapi.

In case of editing an existing contact, it overwrites the existing entry of that id completely. Edit operation is not editing of selected fields, it is replacement of the entire contact/group.

If string value given for Value key is empty, then that field is not added to the contact. Rest of the fields are still added.

If the database does not support Label then, the Label is ignored if it is given (sim database does not support Label).



Table 6.66: Contact(map)
Key Value NA NA
[DBUri] string NA NA
[id] string NA NA
Key1 map NA NA
NA Label NA string
NA Value NA string
Key2 map NA NA
NA Label string NA
NA Value string NA
NA Next map NA


Output Parameters

The output contains ErrorCode and an ErrorMessage if the operation fails.

Table 6.67: Output parameters for Add
Name Type Range Description
ErrorCode int NA Contains the SAPI specific error code when the operation fails.
ErrorMessage string NA Error Description in Engineering English.


Errors

The following table lists the errors and their values:

Table 6.68: Error codes
Error code value Description
0 Success
1002 Bad argument type
1004 Service not supported
1005 Service in use
1011 Access denied


Error Messages

The following table lists the error messages and their description:

Table 6.69: Error messages
Error messages Description
Contacts:Add:Type is missing Indicates Type is missing
Contacts:Add:Invalid Type, must be Contact/Group Indicates invalid value for Type, can have values Contact/Group only.
Contacts:Add:Invalid Sort Type, Map is required Indicates that the sort order type passed is invalid, map is expected
Contacts:Add:Add Data is Missing Indicates that the key Data is missing.
Contacts:Add:Add data Map is Missing indicates that the value of the Data is missing.
Contacts:Add:Group Label is Missing Indicates that the label for group is missing.
Contacts:Add:Mandatory Argument is not present Indicates not all mandatory parameters are present.
Contacts:Add:Type of Contact Id is wrong Indicates that Contact Id value is not a string.
Contacts:Add:Invalid Type of Data, Map is required Indicates that Data value must be of Type map.
Contacts:Add:Invalid Type of Field value, Map is required Indicates that value of a given Key (for example: Key1, Key2), is not a Map.
Contacts:Add:Invalid Type of NextField value, Map is required Indicates that value of Next field is not a Map.
Contacts:Add:Invalid Type of Id Indicates that value Group Id is not a string.
Contacts:Add:Invalid Type of GroupLabel Indicates that value Group Label is not a string.
Contacts:Add:Wrong Type of ContentType Indicates that the value Type is not a string.
Contacts:Add:Atleast one field is required Indicates that atleast one field must be specified.
Contacts:Add:Group Label is Empty Indicates that the mandatory input parameter GroupLabel is an empty string.
Contacts:Add:Invalid Field Key:fieldkey Indicates that the key fieldkey, is not a valid.
Contacts:Add:Field Key Not Supported on this Database:fieldkey Indicates that the fieldkey is not supported on the given database.
Contacts:Add:Field Value too long for key:fieldkey Indicates that the fieldkey has a greater length than the maximum allowed for the particular key.


Example

The following sample code illustrates how to add a contact information: 

# Load contacts module
contacts_handle = scriptext.load('Service.Contact', 'IDataSource')
try:
    contacts_handle.call('Add', {'Type': u'Contact', 'Data':
            	{'FirstName': {'Label': u'first name', 'Value': u'Daniel'},
                 'LastName': {'Label': u'last name', 'Value': u'Craig'},
                 'MobilePhoneGen': {'Label': u'mobile', 'Value': u'9008025211'},
                 'EmailHome': {'Label': u'email', 'Value': u'dcraig@ford.com'}}})
    print "Contact added Successfully"

except scriptext.ScriptextError, err:
    print "Error adding the contact : ", err

Up one Level S60 Module Reference Contents Module Index Index
Previous: Up: 6.4 Contacts Next:
Release 2.0.0 final , documentation updated on 10 Feb 2010.
See About this document... for information on suggesting changes.