rtcom-eventlogger/eventlogger.h File Reference

API for the framework. More...

#include <glib-object.h>
#include "rtcom-eventlogger/event.h"
#include "rtcom-eventlogger/eventlogger-types.h"
#include "rtcom-eventlogger/eventlogger-iter.h"
#include "rtcom-eventlogger/eventlogger-attach-iter.h"
#include "rtcom-eventlogger/eventlogger-query.h"

Go to the source code of this file.

Functions
RTComEl *	rtcom_el_new (void)
RTComEl *	rtcom_el_get_shared (void)
gint	rtcom_el_add_event (RTComEl *el, RTComElEvent *event, GError **error)
gint	rtcom_el_add_event_full (RTComEl *el, RTComElEvent *ev, GHashTable *headers, GList *attachments, GError **error)
const gchar *	rtcom_el_get_last_group_uid (RTComEl *el)
gint	rtcom_el_add_header (RTComEl *el, gint event_id, const gchar *key, const gchar *value, GError **error)
gint	rtcom_el_add_attachment (RTComEl *el, gint event_id, const gchar *path, const gchar *desc, GError **error)
gint	rtcom_el_set_read_event (RTComEl *el, gint event_id, gboolean read, GError **error)
gint	rtcom_el_set_read_events (RTComEl *el, gint *event_ids, gboolean read, GError **error)
gint	rtcom_el_set_event_flag (RTComEl *el, gint event_id, const gchar *flag, GError **error)
gint	rtcom_el_unset_event_flag (RTComEl *el, gint event_id, const gchar *flag, GError **error)
gboolean	rtcom_el_set_end_time (RTComEl *el, gint event_id, time_t end_time, GError **error)
RTComElIter *	rtcom_el_get_events (RTComEl *el, RTComElQuery *query)
RTComElIter *	rtcom_el_get_events_atomic (RTComEl *el, RTComElQuery *query)
GHashTable *	rtcom_el_fetch_event_headers (RTComEl *el, gint event_id)
gint *	rtcom_el_get_events_by_header (RTComEl *el, const gchar *key, const gchar *val)
gint	rtcom_el_get_service_id (RTComEl *el, const gchar *service)
gint	rtcom_el_get_eventtype_id (RTComEl *el, const gchar *eventtype)
gint	rtcom_el_get_flag_value (RTComEl *el, const gchar *flag)
GList *	rtcom_el_get_unique_remote_ebook_uids (RTComEl *el)
GList *	rtcom_el_get_unique_remote_uids (RTComEl *el)
GList *	rtcom_el_get_unique_remote_names (RTComEl *el)
GList *	rtcom_el_get_unique_account_ids (RTComEl *el)
gboolean	rtcom_el_get_group_info (RTComEl *el, const gchar *group_uid, gint *total_events, gint *unread_events, gint *group_flags)
gint	rtcom_el_get_group_most_recent_event_id (RTComEl *el, const gchar *group_uid)
gint	rtcom_el_get_contacts_events_n (RTComEl *el, const gchar *remote_ebook_uid)
gint	rtcom_el_get_local_remote_uid_events_n (RTComEl *el, const gchar *local_uid, const gchar *remote_uid)
gint	rtcom_el_delete_event (RTComEl *el, gint event_id, GError **error)
gboolean	rtcom_el_delete_events (RTComEl *el, RTComElQuery *query, GError **error)
gboolean	rtcom_el_delete_by_service (RTComEl *el, const gchar *service)
gboolean	rtcom_el_delete_by_group_uids (RTComEl *el, const gchar **group_uids)
gboolean	rtcom_el_delete_all (RTComEl *el)
gint	rtcom_el_count_by_service (RTComEl *el, const gchar *service)
gint	rtcom_el_get_flag_id (RTComEl *el, const gchar *flag)
gboolean	rtcom_el_update_remote_contact (RTComEl *el, const gchar *local_uid, const gchar *remote_uid, const gchar *new_abook_uid, const gchar *new_remote_name, GError **error)
gboolean	rtcom_el_update_remote_contacts (RTComEl *el, GList *contacts, GError **error)
gboolean	rtcom_el_remove_abook_uid (RTComEl *el, const gchar *abook_uid, GError **error)
gboolean	rtcom_el_remove_abook_uids (RTComEl *el, GList *uids, GError **error)
gint	rtcom_el_fire_event_updated (RTComEl *el, gint event_id)

---

Detailed Description

API for the framework.

Copyright (C) 2005-06 Nokia Corporation. Contact: Naba Kumar <naba.kumar@nokia.com>

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

This is the only file the user needs to include directly.

Definition in file eventlogger.h.

---

Function Documentation

gint rtcom_el_add_attachment	(	RTComEl *	el,
		gint	event_id,
		const gchar *	path,
		const gchar *	desc,
		GError **	error
	)

Adds an attachment to an event.

Parameters:

	el	The RTComEl object.
	event_id	The id of the event you want to add the attachment to.
	path	The path where the file you want to attach is located.
	desc	A description for the attachment. Can be NULL.
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

The attachment id or -1 in case of error.

Examples:

check_el.c.

gint rtcom_el_add_event	(	RTComEl *	el,
		RTComElEvent *	event,
		GError **	error
	)

Stores an event.

Parameters:

	el	The RTComEl object.
	event	An RTComElEvent object.
	error	A location fo the possible error message. Can be NULL if not interesting.

Returns:

The id of the new event. -1 in case of error.

Examples:

check_el.c.

gint rtcom_el_add_event_full	(	RTComEl *	el,
		RTComElEvent *	ev,
		GHashTable *	headers,
		GList *	attachments,
		GError **	error
	)

Stores an event and all its headers/attachments in one atomic operation.

Parameters:

	el	The RTComEl object.
	ev	An RTComElEvent object.
	headers	A (gchar *name -> gchar *value) mapping of event headers
	attachments	A list of RTComElAttachments to add to the event
	error	A location for the possible error message

Returns:

The ID of new event or -1 in case of failure.

Examples:

check_el.c.

gint rtcom_el_add_header	(	RTComEl *	el,
		gint	event_id,
		const gchar *	key,
		const gchar *	value,
		GError **	error
	)

Adds a custom header to an event.

Parameters:

	el	The RTComEl object.
	event_id	The id of the event you want to add the header to.
	key	The key (or name) for the header.
	value	The value for the header.
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

The header id, or -1 in case of error.

Examples:

check_el.c.

gint rtcom_el_count_by_service	(	RTComEl *	el,
		const gchar *	service
	)

Gets the number of events for a specific service. Could be used for statistical purposes.

Parameters:

	el	The RTComEl object
	service	The service. If NULL, than this function will return the number of all events in the database.

Returns:

the number of events for the service, or -1 in case of error.

gboolean rtcom_el_delete_all

(

RTComEl *

el

)

Removes all events from the db.

Parameters:

el

The RTComEl object

Returns:

TRUE in case of success, FALSE otherwise

gboolean rtcom_el_delete_by_group_uids	(	RTComEl *	el,
		const gchar **	group_uids
	)

Removes all events matching specified group uids

Parameters:

	el	The RTComEl object
	group_uids	A NULL-terminated array of strings

Returns:

TRUE in case of success, FALSE otherwise

gboolean rtcom_el_delete_by_service	(	RTComEl *	el,
		const gchar *	service
	)

Removes all events matching a service.

Parameters:

	el	The RTComEl object
	service	The service

Returns:

TRUE in case of success, FALSE otherwise

gint rtcom_el_delete_event	(	RTComEl *	el,
		gint	event_id,
		GError **	error
	)

Removes an event from the database.

Parameters:

	el	The RTComEl object
	event_id	The id of the event you want to remove
	error	A location for the possible error message. Can be NULL if not interesting

Returns:

-1 in case of error, or 0 in case of success

Examples:

check_el.c.

gboolean rtcom_el_delete_events	(	RTComEl *	el,
		RTComElQuery *	query,
		GError **	error
	)

Removes all the events matching a query.

Parameters:

	el	The RTComEl object
	query	A prepared RTComElQuery
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

FALSE in case of error, TRUE in case of success

Examples:

check_el.c.

GHashTable* rtcom_el_fetch_event_headers	(	RTComEl *	el,
		gint	event_id
	)

Gets all headers of an event from the database.

Parameters:

	el	The RTComEl object
	event_id	The id of the event whose headers you want to fetch

Returns:

An hash table of string:string (key:value)

Examples:

check_el.c.

gint rtcom_el_fire_event_updated	(	RTComEl *	el,
		gint	event_id
	)

Fire EventUpdated DBus signal (only to be used from plugins, to signal their state changed).

Parameters:

	el	The RTComEl object.
	event_id	The id of the event that should be signalled as updated.

Returns:

0 if success, -1 if failure.

gint rtcom_el_get_contacts_events_n	(	RTComEl *	el,
		const gchar *	remote_ebook_uid
	)

Returns the number of events for a certain remote-ebook-uid.

Parameters:

	el	The RTComEl object
	remote_ebook_uid	the remote-ebook-uid

Returns:

The number of events in the database

RTComElIter* rtcom_el_get_events	(	RTComEl *	el,
		RTComElQuery *	query
	)

Retrieves events from the database. Returns an iterator to the first event in the constructed query, or NULL if an error occurred or none found.

Parameters:

	el	The RTComEl object
	query	The RTComElQuery to perform

Returns:

An iterator to the events.

Examples:

check_el.c.

RTComElIter* rtcom_el_get_events_atomic	(	RTComEl *	el,
		RTComElQuery *	query
	)

Retrieves events from the database in an atomic way. Like rtcom_el_get_events, but the returned iterator is guarded by transactional brackets, so the table contents are guaranteed not to be changed by other processess. Care must be taken that the iterator is properly unreffed to release the database lock, and that no event addition/modification is done in the meantime (because there's no support for nested transactions). Returns an iterator to the first event in the constructed query, or NULL if an error occurred or none found.

Parameters:

	el	The RTComEl object
	query	The RTComElQuery to perform

Returns:

An iterator to the events.

gint* rtcom_el_get_events_by_header	(	RTComEl *	el,
		const gchar *	key,
		const gchar *	val
	)

Gets all event-ids that match a certain key:value in the Headers table..

Parameters:

	el	The RTComEl object
	key	The header key
	val	The header value

Returns:

An array of gints, whose last element is -1, or NULL in case of error. Please free the array with g_free.

gint rtcom_el_get_eventtype_id	(	RTComEl *	el,
		const gchar *	eventtype
	)

Retrieves the id of an event-type.

Parameters:

	el	The RTComEl object.
	eventtype	The name of the event-type.

Returns:

The id of the event-type, or -1 if not found.

Examples:

check_el.c.

gint rtcom_el_get_flag_id	(	RTComEl *	el,
		const gchar *	flag
	)

Returns the id of a Flag.

Parameters:

	el	The RTComEl object
	flag	The name of the Flag

Returns:

-1 in case of error, or the id of the requested Flag

gint rtcom_el_get_flag_value	(	RTComEl *	el,
		const gchar *	flag
	)

Retrieve the value of a flag.

FIXME: use of a db table to map strings to integer flags is an utter waste of CPU time. Define and document your flag values, use them consistently throughout your database. If you must, then at least prepare the query once per lifetime of a RTComEl and bind flag strings to it.

Parameters:

	el	The RTComEl object.
	flag	The name of the flag.

Returns:

The value of the flag, or -1 if not found.

Examples:

check_el.c.

gboolean rtcom_el_get_group_info	(	RTComEl *	el,
		const gchar *	group_uid,
		gint *	total_events,
		gint *	unread_events,
		gint *	group_flags
	)

Returns information about a group of events.

Parameters:

	el	The RTComEl object
	group_uid	The group_uid that identidies the group
	total_events	A placeholder for the number of events in the group
	unread_events	A placeholder for the number of unread evetents in the group
	group_flags	The boolean OR of the flags of all the events in the group

Returns:

TRUE in case of success, FALSE otherwise

gint rtcom_el_get_group_most_recent_event_id	(	RTComEl *	el,
		const gchar *	group_uid
	)

Returns the id of the most recent event in a group.

Parameters:

	el	The RTComEl object
	group_uid	the UID of the group

Returns:

the id of the most recent event in the group

const gchar* rtcom_el_get_last_group_uid

(

RTComEl *

el

)

Returns the group-uid of the event you added last. This is useful if you start logging a chat conversation, get a group-uid from here after logging the first message, and then keep using the same group-uid for the rest of the messages in the same conversation.

Parameters:

el

The RTComEl object return The group-uid of an added event, or NULL if not applicable.

gint rtcom_el_get_local_remote_uid_events_n	(	RTComEl *	el,
		const gchar *	local_uid,
		const gchar *	remote_uid
	)

Returns the number of events for a certain pair of local_uid and remote_uid.

Parameters:

	el	The RTComEl object
	local_uid	The local_uid
	remote_uid	The remote_uid

Returns:

The number of events, or -1 in case of error.

gint rtcom_el_get_service_id	(	RTComEl *	el,
		const gchar *	service
	)

Retrieves the id of a service.

Parameters:

	el	The RTComEl object.
	service	The name of the service.

Returns:

The service-id, or -1 if not found.

Examples:

check_el.c.

RTComEl* rtcom_el_get_shared

(

void

)

Returns a new reference to the shared instance of a singleton RTComEl object. This method is not thread-safe.

Returns:

A new reference to an RTComEl object. Should be unreffed after use.

GList* rtcom_el_get_unique_account_ids

(

RTComEl *

el

)

Retrieve all the unique account identifiers in the db. An account identifier is a string made of the concatenation of the remote-ebook-uid and the "mc-account-name" header, if present.

Parameters:

el

The RTComEl object

Returns:

a GList containing a const gchar * for each unique account identifiers in the db

GList* rtcom_el_get_unique_remote_ebook_uids

(

RTComEl *

el

)

Retrieve all the unique remote_ebook_uid's in the db.

Parameters:

el

The RTComEl object

Returns:

a GList containing a const gchar * for each unique remote_ebook_uid in the db

Examples:

check_el.c.

GList* rtcom_el_get_unique_remote_names

(

RTComEl *

el

)

Retrieve all the unique remote_name's in the db.

Parameters:

el

The RTComEl object

Returns:

a GList containing a const gchar * for each unique remote_name in the db

Examples:

check_el.c.

GList* rtcom_el_get_unique_remote_uids

(

RTComEl *

el

)

Retrieve all the unique remote_uid's in the db.

Parameters:

el

The RTComEl object

Returns:

a GList containing a const gchar * for each unique remote_uid in the db

Examples:

check_el.c.

RTComEl* rtcom_el_new

(

void

)

Creates a new RTComEl.

Returns:

A newly allocated RTComEl. It's a GObject, so use g_object_unref to free.

Examples:

check_el.c.

gboolean rtcom_el_remove_abook_uid	(	RTComEl *	el,
		const gchar *	abook_uid,
		GError **	error
	)

Removes any association with the specified abook uid.

Parameters:

	el	the RTComEl object
	abook_uid	the abook ID for the contact
	error	A GError** to be set on failure

Returns:

TRUE on success, FALSE in case of failure

gboolean rtcom_el_remove_abook_uids	(	RTComEl *	el,
		GList *	uids,
		GError **	error
	)

A plural version of rtcom_el_remove_abook_uid() for batch updates.

Parameters:

	el	the RTComEl object
	uids	a GList* of gchar * abook uids to be cleared
	error	a GError** to be set on failure

Returns:

TRUE on success, FALSE in case of failure

gboolean rtcom_el_set_end_time	(	RTComEl *	el,
		gint	event_id,
		time_t	end_time,
		GError **	error
	)

Sets the end-time property of an event.

Parameters:

	el	The RTComEl object
	event_id	The id of the event
	end_time	The end-time property A location for the possible error message. Can be NULL if not interesting

Returns:

TRUE in case of success, FALSE otherwise

gint rtcom_el_set_event_flag	(	RTComEl *	el,
		gint	event_id,
		const gchar *	flag,
		GError **	error
	)

Sets a flag for an event.

Parameters:

	el	The RTComEl object
	event_id	The id of the event
	flag	The name of the flag
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

0 if success, -1 if failure

Examples:

check_el.c.

gint rtcom_el_set_read_event	(	RTComEl *	el,
		gint	event_id,
		gboolean	read,
		GError **	error
	)

Marks an event as read/unread.

Parameters:

	el	The RTComEl object.
	event_id	The id of the event you want to mark as read/unread.
	read	TRUE if you want to mark read, FALSE if you want to mark unread.
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

0 if success, -1 if failure.

Examples:

check_el.c.

gint rtcom_el_set_read_events	(	RTComEl *	el,
		gint *	event_ids,
		gboolean	read,
		GError **	error
	)

Marks multiple events as read/unread.

Parameters:

	el	The RTComEl object.
	event_ids	An array of ids of events. Must be NULL terminated.
	read	TRUE if you want to mark read, FALSE if you want to mark unread.
	error	A location for the possible error message. Can be NULL if not interesting. Returns 0 if success, -1 if failure.

Examples:

check_el.c.

gint rtcom_el_unset_event_flag	(	RTComEl *	el,
		gint	event_id,
		const gchar *	flag,
		GError **	error
	)

Unsets a flag for an event.

Parameters:

	el	The RTComEl object
	event_id	The id of the event
	flag	The name of the flag
	error	A location for the possible error message. Can be NULL if not interesting.

Returns:

0 if success, -1 if failure

gboolean rtcom_el_update_remote_contact	(	RTComEl *	el,
		const gchar *	local_uid,
		const gchar *	remote_uid,
		const gchar *	new_abook_uid,
		const gchar *	new_remote_name,
		GError **	error
	)

Updates the remote contact data.

Parameters:

	el	the RTComEl object
	local_uid	the ID for the account on the contact is being changed
	remote_uid	the remote contact ID
	new_abook_uid	new abook ID for this contact
	new_remote_name	new remote name (to be cached) for this contact
	error	A GError** to be set on failure

Returns:

TRUE on succes, FALSE in case of failure

gboolean rtcom_el_update_remote_contacts	(	RTComEl *	el,
		GList *	contacts,
		GError **	error
	)

A plural version of rtcom_el_update_remote_contact() for batch updates

Parameters:

	el	the RTComEl object
	contacts	a Glist* of RTComElRemote structs
	error	A GError** to be set on failure

Returns:

TRUE on succes, FALSE in case of failure