Common

---

The contacts common API provides the set of definitions and interfaces to initialize and deinitialize.

Required Header

#include <contacts.h>

Functions
int	contacts_connect (void)
	Connects to the contacts service.
int	contacts_disconnect (void)
	Disconnects from the contacts service.
int	contacts_connect_on_thread (void)
	Connects to the contacts service with a connection on another thread.
int	contacts_disconnect_on_thread (void)
	Disconnects from the contacts service.
int	contacts_connect_with_flags (unsigned int flags)
	Connects to the contacts service.
Defines
#define	CONTACTS_CONNECT_FLAG_RETRY   0x00000001
	Definition for contacts_connect_with_flags(). If it is called the API with this flag, then retry to call contacts_connect() for several times.
#define	CONTACTS_CONNECT_FLAG_NONE   0
	Definition for default flag of contacts_connect_with_flags().

---

Define Documentation

#define CONTACTS_CONNECT_FLAG_NONE   0

Definition for default flag of contacts_connect_with_flags().

Since :

2.3

See also:

contacts_connect_with_flags()

#define CONTACTS_CONNECT_FLAG_RETRY   0x00000001

Definition for contacts_connect_with_flags(). If it is called the API with this flag, then retry to call contacts_connect() for several times.

Since :

2.3

See also:

contacts_connect_with_flags()

---

Enumeration Type Documentation

enum contacts_error_e

Enumeration for contacts errors.

Since :

2.3

Enumerator:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_FILE_NO_SPACE	FS Full
CONTACTS_ERROR_PERMISSION_DENIED	Permission denied
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_NO_DATA	Requested data does not exist
CONTACTS_ERROR_DB_LOCKED	Database table locked or file locked
CONTACTS_ERROR_DB	Unknown DB error
CONTACTS_ERROR_IPC_NOT_AVALIABLE	IPC server is not available
CONTACTS_ERROR_IPC	Unknown IPC error
CONTACTS_ERROR_SYSTEM	Internal system module error
CONTACTS_ERROR_INTERNAL	Implementation Error, Temporary Use

---

Function Documentation

int contacts_connect

(

void

)

Connects to the contacts service.

Since :

2.3

Remarks:

Connection opening is necessary to access the contacts server such as fetching, inserting, or updating records.
The execution of contacts_connect() and contacts_disconnect() could slow down your application. So it is not recommended to call them frequently.

Returns:

0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_IPC	IPC error
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	System error
CONTACTS_ERROR_INTERNAL	Internal error

See also:

contacts_disconnect()

int contacts_connect_on_thread

(

void

)

Connects to the contacts service with a connection on another thread.

Since :

2.3

Remarks:

Opening connection is necessary to access the contact server and to perform operations such as fetching, inserting, or updating records.
On multiple thread environment with contacts_connect(), request can be failed in one thread, while another request is working by the connection in the other thread. To prevent request fail, contacts_connect_on_thread() is recommended. Then new connection is set for the thread.

Returns:

0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_IPC	IPC error
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	System error
CONTACTS_ERROR_INTERNAL	Internal error

See also:

contacts_disconnect_on_thread()

int contacts_connect_with_flags

(

unsigned int

flags

)

Connects to the contacts service.

Since :

2.3

Parameters:

[in]

flags

Connection flag

Remarks:

Connection opening is necessary to access the contacts server such as fetching, inserting, or updating records.
Before contacts-service daemon is ready, if you call contacts_connect(), it will fail. To prevent it, if you call this API with CONTACTS_CONNECT_FLAG_RETRY flags, it will retry several time.
To close the connection, contacts_disconnect() should be called.

Returns:

0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_IPC	IPC error
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	System error
CONTACTS_ERROR_INTERNAL	Internal error

See also:

contacts_disconnect()

int contacts_disconnect

(

void

)

Disconnects from the contacts service.

Since :

2.3

Remarks:

If there is no opened connection, this function returns CONTACTS_ERROR_DB.

Returns:

0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_IPC	IPC error
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	System error
CONTACTS_ERROR_DB	Database operation failure

See also:

contacts_connect()

int contacts_disconnect_on_thread

(

void

)

Disconnects from the contacts service.

Since :

2.3

Remarks:

If there is no opened connection, this function returns CONTACTS_ERROR_DB.

Returns:

0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_IPC	IPC error
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	System error
CONTACTS_ERROR_DB	Database operation failure

See also:

contacts_connect_on_thread()