6.4.4 Import
Import
is used to import a contact to a contacts database. The information must be imported from a VCard file. This API can be called both in synchronous and asynchronous mode.
The following is an example for using Import
:
Asynchronous
event_id = contacts_handle.call('Import', {'Type': u'Contact','Data':{'SourceFile':u'c:\\Data\\python\\VCARD.txt'}},callback=get_import)
where, get_import
is a user defined callback function.
The following table summarizes the specification of Import
:
Interface |
IDataSource |
Operation |
Imports contact to the specified contacts database. |
Response Model |
Asynchronous and synchronous for Third Edition FP2 and Fifth Edition devices.
Synchronous for Third Edition and Third Edition FP1 devices. |
Pre-condition |
IDataSource interface is loaded. |
Post-condition |
Updates database with imported contact. |
Input Parameters
Input parameter specifies the contact to import and optionally the target database.
Table 6.74:
Input parameters Import
Name |
Type |
Range |
Description |
Type |
unicode string |
Contact |
Operation is performed on the specified type. |
Data |
map
[DBUri] : unicode string
SourceFile : unicode string |
All string values in the map are unicode.
Note:
SourceFile can have any extension or no extension.
SourceFile has to be in Vcard format.
Example of vcard format:
BEGIN:VCARD
VERSION:2.1
N:Kent; Clark
FN:Clark Kent
ORG:Superman Inc.
TITLE:Super Man
TEL;WORK:VOICE:(111) 556-9898
TEL;HOME;VOICE:(090) 556-6767
ADR;WORK:;;3rd Rock from Sun;Solar System;Milky Way
LABEL;WORK;ENCODING=QUOTED-PRINTABLE:3rd Rock from Sun=0D=0ASolar System=0D=0AMilky Way
ADR;HOME:;;Krypton
LABEL;HOME;ENCODING=QUOTED-PRINTABLE:Krypton
EMAIL;PREF;INTERNET:clarkkent@krypton.com
REV:2008042T195243Z
END:VCARD
|
DBUri : Imports contact to the specified database or to the default database if not specified.
SourceFile : Imports contact from the specified file. SourceFile is the complete path to the file. It cannot be greater than 256 characters. |
|
Output Parameters
The output is an object, which contains ErrorCode
and an ErrorMessage
if the operation fails.
Table 6.75:
Output parameters for Import
Name |
Type |
Range |
Description |
ErrorCode |
int |
NA |
Contains the SAPI specific error code when the operation fails and SErrNone on success. |
ErrorMessage |
string |
NA |
Error Description in Engineering English. |
|
Errors
The following table lists the errors and their values:
Table 6.76:
Error codes
Error code value |
Description |
1002 |
Bad argument type |
1011 |
Access denied |
1017 |
Path not found |
|
Error Messages
The following table lists the error messages and their description:
Table 6.77:
Error messages
Error messages |
Description |
Contacts:Import:Type is missing |
Indicates Type is missing |
Contacts:Import:Invalid Type, it must be Contact |
Indicates invalid value for Type, it can be only Contact. |
Contacts:Import:Import data Missing |
Indicates that the key Data is missing. |
Contacts:Import:Invalid Type of Data, Map is required |
Indicates that the value of the Data is not a Map. |
Contacts:Import:Import Source Filename is Missing |
Indicates the argument to signify the filename of the imported file is missing. |
Contacts:Import:Import Source File is not a String |
Indicates that the filename specified is not a string. |
Contacts:Import:Wrong Type of ContentType |
Indicates that the value for Type is not a string. |
Contacts:Import:Mandatory Argument is not present |
Indicates that not all mandatory parameters are present. |
Contacts:Import:Import DataBaseUri is not a String |
Indicates that the uri specified is not a string. |
Contacts:Import:Filename too long |
Indicates that filename has exceeded 256 characters. |
|
Example
The following sample code illustrates how to import contacts from a VCard format file:
import scriptext
import e32
# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()
# Callback function will be called when the requested service is complete
def get_import(trans_id, event_id, input_params):
if event_id != scriptext.EventCompleted:
# Check the event status
print "Error in retrieving required info"
print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
if "ErrorMessage" in input_params["ReturnValue"]:
print "Error message:" + input_params["ReturnValue"]["ErrorMessage"]
else:
print "The contacts are imported"
lock.signal()
# Load contacts module
contacts_handle = scriptext.load("Service.Contact", "IDataSource")
event_id = contacts_handle.call('Import', {
'Type': u'Contact',
'Data':{'SourceFile': u'c:\\Data\\python\\VCARD.txt'}}, callback=get_import)
print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"
Release 1.9.6 final , documentation updated on 30 Jun 2009.
See About this document... for information on suggesting changes.