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.

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 parameter specifies the contact to import and optionally the target database.

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 is given below

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.

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

The output is an object, which contains ErrorCode and an ErrorMessage if the operation fails.

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.

Error code value	Description
`1002`	Bad argument type
`1011`	Access denied
`1017`	Path not found

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.

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!"