Evolution Developer's Guide
<<< Previous PageHomeUpNext Page >>>

CalClient

Name

CalClient -- GTK+ object for communication with personal calendar server.

Synopsis


#include <cal-client/cal-client.h>


#define     CAL_CLIENT                      (obj)
enum        CalClientOpenStatus;
enum        CalClientGetStatus;
enum        CalClientLoadState;
enum        CalClientChangeType;
CalClient*  cal_client_new                  (void);
gboolean    cal_client_open_calendar        (CalClient *client,
                                             const char *str_uri,
                                             gboolean only_if_exists);
CalClientLoadState cal_client_get_load_state
                                            (CalClient *client);
const char* cal_client_get_uri              (CalClient *client);
int         cal_client_get_n_objects        (CalClient *client,
                                             CalObjType type);
GList*      cal_client_get_uids             (CalClient *client,
                                             CalObjType type);
CalClientGetStatus cal_client_get_object    (CalClient *client,
                                             const char *uid,
                                             CalComponent **comp);
GList*      cal_client_get_changes          (CalClient *client,
                                             CalObjType type,
                                             const char *change_id);
void        cal_client_change_list_free     (GList *list);
GList*      cal_client_get_objects_in_range (CalClient *client,
                                             CalObjType type,
                                             time_t start,
                                             time_t end);
void        cal_client_generate_instances   (CalClient *client,
                                             CalObjType type,
                                             time_t start,
                                             time_t end,
                                             CalRecurInstanceFn cb,
                                             gpointer cb_data);
GSList*     cal_client_get_alarms_in_range  (CalClient *client,
                                             time_t start,
                                             time_t end);
void        cal_client_free_alarms          (GSList *comp_alarms);
gboolean    cal_client_get_alarms_for_object
                                            (CalClient *client,
                                             const char *uid,
                                             time_t start,
                                             time_t end,
                                             CalComponentAlarms **alarms);
gboolean    cal_client_update_object        (CalClient *client,
                                             CalComponent *comp);
gboolean    cal_client_remove_object        (CalClient *client,
                                             const char *uid);
CalQuery*   cal_client_get_query            (CalClient *client,
                                             const char *sexp);

Object Hierarchy


  GtkObject
   +----CalClient

Signal Prototypes


"cal-opened"
            void        user_function      (CalClient *calclient,
                                            gint arg1,
                                            gpointer user_data);
"cal-set-mode"
            void        user_function      (CalClient *calclient,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);
"obj-updated"
            void        user_function      (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);
"obj-removed"
            void        user_function      (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);
"categories-changed"
            void        user_function      (CalClient *calclient,
                                            gpointer arg1,
                                            gpointer user_data);
"forget-password"
            void        user_function      (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);

Description

The CalClient object provides a nice GTK+ wrapper for the CORBA interfaces that are used to communicate between calendar clients and the personal calendar server in the user's Wombat daemon. The CORBA interfaces transfer calendar components in RFC 2445 text format; the CalClient object automatically converts these into CalComponent structures that are easier to handle.

After a CalClient object is created with cal_client_new(), it should be asked to send a request to the personal calendar server to load or create a calendar based on its URI. The server will asynchronously notify the client about completion of the request, and will return an appropriate result code; this should be noted by the client with the cal_loaded signal.

When a client asks the server to update or delete a calendar component from the storage, the server will do so and then notify all the clients about the update or removal. This is the core of the model/view split between calendar clients and the storage in the personal calendar server. Clients should watch the obj_updated and obj_removed signals on the CalClient objects they create so that they can be notified about changes in the storage.

Details

CAL_CLIENT()

#define CAL_CLIENT(obj)            (GTK_CHECK_CAST ((obj), CAL_CLIENT_TYPE, CalClient))

Casts a GtkObject to a CalClient.

obj :A GTK+ object.

enum CalClientOpenStatus

typedef enum {
	CAL_CLIENT_OPEN_SUCCESS,
	CAL_CLIENT_OPEN_ERROR,
	CAL_CLIENT_OPEN_NOT_FOUND,
	CAL_CLIENT_OPEN_METHOD_NOT_SUPPORTED
} CalClientOpenStatus;

enum CalClientGetStatus

typedef enum {
	CAL_CLIENT_GET_SUCCESS,
	CAL_CLIENT_GET_NOT_FOUND,
	CAL_CLIENT_GET_SYNTAX_ERROR
} CalClientGetStatus;

These values describe the result of the cal_client_get_object() function.

enum CalClientLoadState

typedef enum {
	CAL_CLIENT_LOAD_NOT_LOADED,
	CAL_CLIENT_LOAD_LOADING,
	CAL_CLIENT_LOAD_LOADED
} CalClientLoadState;

enum CalClientChangeType

typedef enum {
	CAL_CLIENT_CHANGE_ADDED = 1 << 0,
	CAL_CLIENT_CHANGE_MODIFIED = 1 << 1,
	CAL_CLIENT_CHANGE_DELETED = 1 << 2
} CalClientChangeType;

cal_client_new ()

CalClient*  cal_client_new                  (void);

Creates a new calendar client. It should be initialized by calling cal_client_open_calendar().

Returns : A newly-created calendar client, or NULL if the client could not be constructed because it could not contact the calendar server.

cal_client_open_calendar ()

gboolean    cal_client_open_calendar        (CalClient *client,
                                             const char *str_uri,
                                             gboolean only_if_exists);

Makes a calendar client initiate a request to open a calendar. The calendar client will emit the "cal_opened" signal when the response from the server is received.

client : A calendar client.
str_uri : URI of calendar to open.
only_if_exists : FALSE if the calendar should be opened even if there was no storage for it, i.e. to create a new calendar or load an existing one if it already exists. TRUE if it should only try to load calendars that already exist.
Returns : TRUE on success, FALSE on failure to issue the open request.

cal_client_get_load_state ()

CalClientLoadState cal_client_get_load_state
                                            (CalClient *client);

Queries the state of loading of a calendar client.

client : A calendar client.
Returns : A CalClientLoadState value indicating whether the client has not been loaded with cal_client_open_calendar() yet, whether it is being loaded, or whether it is already loaded.

cal_client_get_uri ()

const char* cal_client_get_uri              (CalClient *client);

Queries the URI that is open in a calendar client.

client : A calendar client.
Returns : The URI of the calendar that is already loaded or is being loaded, or NULL if the client has not started a load request yet.

cal_client_get_n_objects ()

int         cal_client_get_n_objects        (CalClient *client,
                                             CalObjType type);

Counts the number of calendar components of the specified type. This can be used to count how many events, to-dos, or journals there are, for example.

client : A calendar client.
type : Type of objects that will be counted.
Returns : Number of components.

cal_client_get_uids ()

GList*      cal_client_get_uids             (CalClient *client,
                                             CalObjType type);

Queries a calendar for a list of unique identifiers corresponding to calendar objects whose type matches one of the types specified in the type flags.

client : A calendar client.
type : Bitmask with types of objects to return.
Returns : A list of strings that are the sought UIDs. This should be freed using the cal_obj_uid_list_free() function.

cal_client_get_object ()

CalClientGetStatus cal_client_get_object    (CalClient *client,
                                             const char *uid,
                                             CalComponent **comp);

Queries a calendar for a calendar component object based on its unique identifier.

client : A calendar client.
uid : Unique identifier for a calendar component.
comp : Return value for the calendar component object.
Returns : Result code based on the status of the operation.

cal_client_get_changes ()

GList*      cal_client_get_changes          (CalClient *client,
                                             CalObjType type,
                                             const char *change_id);

client : 
type : 
change_id : 
Returns : 

cal_client_change_list_free ()

void        cal_client_change_list_free     (GList *list);

Frees a list of CalClientChange structures.

list : List of CalClientChange structures.

cal_client_get_objects_in_range ()

GList*      cal_client_get_objects_in_range (CalClient *client,
                                             CalObjType type,
                                             time_t start,
                                             time_t end);

Queries a calendar for the objects that occur or recur in the specified range of time.

client : A calendar client.
type : Bitmask with types of objects to return.
start : Start time for query.
end : End time for query.
Returns : A list of UID strings. This should be freed using the cal_obj_uid_list_free() function.

cal_client_generate_instances ()

void        cal_client_generate_instances   (CalClient *client,
                                             CalObjType type,
                                             time_t start,
                                             time_t end,
                                             CalRecurInstanceFn cb,
                                             gpointer cb_data);

Does a combination of cal_client_get_objects_in_range() and cal_recur_generate_instances(). It fetches the list of objects in an atomic way so that the generated instances are actually in the server at the time the initial cal_client_get_objects_in_range() query ends.

The callback function should do a gtk_object_ref() of the calendar component it gets passed if it intends to keep it around.

client : A calendar client.
type : Bitmask with types of objects to return.
start : Start time for query.
end : End time for query.
cb : Callback for each generated instance.
cb_data : Closure data for the callback.

cal_client_get_alarms_in_range ()

GSList*     cal_client_get_alarms_in_range  (CalClient *client,
                                             time_t start,
                                             time_t end);

Queries a calendar for the alarms that trigger in the specified range of time.

client : A calendar client.
start : Start time for query.
end : End time for query.
Returns : A list of CalComponentAlarms structures. This should be freed using the cal_client_free_alarms() function, or by freeing each element separately with cal_component_alarms_free() and then freeing the list with g_slist_free().

cal_client_free_alarms ()

void        cal_client_free_alarms          (GSList *comp_alarms);

Frees a list of CalComponentAlarms structures as returned by cal_client_get_alarms_in_range().

comp_alarms : A list of CalComponentAlarms structures.

cal_client_get_alarms_for_object ()

gboolean    cal_client_get_alarms_for_object
                                            (CalClient *client,
                                             const char *uid,
                                             time_t start,
                                             time_t end,
                                             CalComponentAlarms **alarms);

Queries a calendar for the alarms of a particular object that trigger in the specified range of time.

client : A calendar client.
uid : Unique identifier for a calendar component.
start : Start time for query.
end : End time for query.
alarms : Return value for the component's alarm instances. Will return NULL if no instances occur within the specified time range. This should be freed using the cal_component_alarms_free() function.
Returns : TRUE on success, FALSE if the object was not found.

cal_client_update_object ()

gboolean    cal_client_update_object        (CalClient *client,
                                             CalComponent *comp);

Asks a calendar to update a component. Any existing component with the specified component's UID will be replaced. The client program should not assume that the object is actually in the server's storage until it has received the "obj_updated" notification signal.

client : A calendar client.
comp : A calendar component object.
Returns : TRUE on success, FALSE on specifying an invalid component.

cal_client_remove_object ()

gboolean    cal_client_remove_object        (CalClient *client,
                                             const char *uid);

Asks a calendar to remove a component. If the server is able to remove the component, all clients will be notified and they will emit the "obj_removed" signal.

client : A calendar client.
uid : Unique identifier of the calendar component to remove.
Returns : TRUE on success, FALSE on specifying a UID for a component that is not in the server. Returning FALSE is normal; the object may have disappeared from the server before the client has had a chance to receive the corresponding notification.

cal_client_get_query ()

CalQuery*   cal_client_get_query            (CalClient *client,
                                             const char *sexp);

Creates a live query object from a loaded calendar.

client : A calendar client.
sexp : S-expression representing the query.
Returns : A query object that will emit notification signals as calendar components are added and removed from the query in the server.

Signals

The "cal-opened" signal

void        user_function                  (CalClient *calclient,
                                            gint arg1,
                                            gpointer user_data);

calclient :the object which received the signal.
arg1 : 
user_data :user data set when the signal handler was connected.

The "cal-set-mode" signal

void        user_function                  (CalClient *calclient,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);

calclient :the object which received the signal.
arg1 : 
arg2 : 
user_data :user data set when the signal handler was connected.

The "obj-updated" signal

void        user_function                  (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);

This signal is emitted when the calendar clients receives notification of a calendar component's data being changed in the personal calendar server. Graphical clients may want to get the new version of the object and update their display, for example.

calclient :the object which received the signal.
arg1 : 
user_data :user data set when the signal handler was connected.

The "obj-removed" signal

void        user_function                  (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);

This signal is emitted when the calendar client receives notification for a calendar component being removed from the storage in the personal calendar server. Graphical clients may want to delete the corresponding object from their display, for example.

calclient :the object which received the signal.
arg1 : 
user_data :user data set when the signal handler was connected.

The "categories-changed" signal

void        user_function                  (CalClient *calclient,
                                            gpointer arg1,
                                            gpointer user_data);

calclient :the object which received the signal.
arg1 : 
user_data :user data set when the signal handler was connected.

The "forget-password" signal

void        user_function                  (CalClient *calclient,
                                            gchar *arg1,
                                            gpointer user_data);

calclient :the object which received the signal.
arg1 : 
user_data :user data set when the signal handler was connected.

See Also

CalComponent



<<< Previous PageHomeUpNext Page >>>
Calendar Public API ReferenceCalComponent