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) |
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_remove_abook_uid (RTComEl *el, const gchar *abook_uid, 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 <[email protected]>
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:
-
- 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.
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.
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:
-
- 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:
-
- 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:
-
- 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:
-
- 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_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