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


Generated on Thu Jun 17 14:07:13 2010 for rtcom-eventlogger by  doxygen 1.5.6