1. Overview.. 1

1.1 how to compile the library. 2

1.2 how to cross-compile the library. 2

1.3 how to compile and run the applications based on the library. 2

2. Core reference. 3

2.1 architecture. 3

2.2 core data structures. 3

2.3 main process of accessing to evenbook. 4

2.4 data storage. 5

2.5 alarm mechanism.. 5

3. Write applications with libcalenabler 6

 

 

 

1. Overview

 

Libcalenabler is a library providing basic functions for calendaring and scheduling applications. It works on UNIX-like platforms. Libcalenabler is released under LIPS (Linux Phone Standard) license. It conforms to LIPS calendaring and scheduling enabler API.

Libcalenabler has been designed as a middle layer which provides only the basic and core calendaring and scheduling functions, such as data management, date and time calculation, alarm job management. It's independent from the implementation of the specific applications. Applications can choose their own GUI solutions as they like. It's possible for different calendaring applications to call libcalenabler as the low layer library.

Libcalenabler has been implemented as a light weighted C library orienting to embedded environment. Glib-2.0, sqlite3 and uuid are the prerequisites to use the library.

 

    1.1 how to compile the library

 

Before you can compile the library, you need to have various other tools installed on your system. The two tools needed during the build process are "pkg-config" and "GNU make".

Libcalenabler depends on a number of other libraries: Glib-2.0, sqlite3 and uuid. GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. SQLite3 is a small C library that implements a self-contained, embeddable, zero-configuration SQL database engine. Uuid (Universally Unique Identifier) is used as the identification of object. You should already have these packages installed before you install libcalenabler.

The library uses the standard GNU build system, using autoconf for package configuration and resolving portability issues, automake for building makefiles that comply with GNU Coding Standards, and libtool for building shared libraries on multiple platforms. The normal sequence for compiling and installing the library is:

            ./autogen.sh

            ./configure

            make

            make install

The standard options provided by GNU autoconf may be passed to the "configure" script. Please see the autoconf documentation or run "./configure ¨Chelp" for information about the standard options.

    1.2 how to cross-compile the library

    1.3 how to compile and run the applications based on the library

To compile applications based on the library, you need to tell the compiler where to find the libcalenabler header files and libraries. This is done with the pkg-config utility. The following sentence should be added to the "configure.ac" in the application:

PKG_CHECK_MODULES (CAL, libcalenabler)

 

2. Core reference

2.1 architecture

 

Following graph depicts the whole architecture of libcalenabler.

                                    Figure 1 architecture of libcalenabler  

Note: The broken line in the graph represents to IPC communication.

As we can see, libcalenabler provides the unique interfaces to applications. Application developers can implement their own calendaring and scheduling applications with the interface, without regarding to the inner mechanism of the library.

Libcalenabler use sqlite3 library to manage the database, which make the data rendering fast and convenient.

As we can see from the graph, atd daemon is a separate process to render the alarm job. Libcalenabler maintains an alarm job list for the events which have alarm. When an alarm job is added(/removed) to(/from) the alarm job list, the atd daemon will be notified to reset the latest timer to the RTC device.  When the time is up, RTC will send an interrupt to the atd daemon, and the atd will be woken up to execute the scheduled job.

 

2.2 core data structures

 

There are two core data structures in calendar enabler: ¡°cal_event_t¡± and "cal_eventbook_t".

A variable of the type "cal_event_t" can represent a calendaring and scheduling event. It contains the following fields:

A series of functions are provided to get/set fields of "cal_event_t" variables.

A variable of the type "cal_eventbook_t" represents a collection of events. Functions are provided to retrieve, add, remove or update events in it. This structure contains following fields:

 

    2.3 main process of accessing to evenbook

 

Prior to access to an calendar backend, application shall establish a connection with the backend using the eventbook_connect() function.

In this function, the database in the backend is opend and the database handle is stored in the "cal_eventbook_t" variable.

cal_eventbook_t *eventbook_connect (cal_uint32_t id);

Once established, "cal_eventbook_t" will be returned and can be used to access to the data contained in the backend.

cal_err_t eventbook_add_event (cal_eventbook_t  *book,

                                          cal_event_t  *event);

cal_err_t eventbook_remove_event (cal_eventbook_t  *book,

                                                          cal_cahr_t  *uid);

... ¡­

When it's not needed any more, you can call the following function to closes the connection. The "cal_eventbook_t" instance will be destroyed then.

cal_err_t eventbook_disconnect    (cal_eventbook­_t  *book);

    2.4 data storage

 

Libcalenabler keeps four tables in the database:

In this table, all events' in formation except for category and event exceptions are stored. Each event has one row in the table.

For example:

tid0

(uid)

tid1

(description)

tid2

(location)

tid3

(notes)

tid4

(start time)

tid5

(endtime)

¡­

1wij¡­¡­

Meeting

1st room

Weekly meeting

200702010800

200702010900

 

¡­

 

 

 

 

 

 

 

In this table, the exceptions in repeating events are stored.

For example:

Uid

Exception

1wij¡­¡­

20070201

¡­

¡­

¡­

¡­

If a repeating event has several exceptions, there will be several rows for the event in the table.

In this table, the categories the events belong to are stored. One event may belong to several categories. Therefore, one event can have several rows in the table.

In this table, there's one row for each alarm job. The alarm id, event id corresponding to the alarm, and the alarm time is stored. For detail description ,pls refer to section 2.5.

 

    2.5 alarm mechanism

 

The alarm mechanism can be shown by the following picture.

Figure 2 alarm mechanism

Libcalenabler maintains an alarm job list on flash. It's a directory, for example "/var/spool/at". Each alarm job is stored as a file in this directory.

The common work flow:

  1. A new event is added to the database by calling the libcalenabler interface: "eventbook_add_event()". The event will be checked. If alarm field is set for the event, libcalenabler will add a new alarm job to the alarm job list, add new records to the tables in the database, and send message to the atd daemon.
  2. The atd daemon receives the message. It scans the alarm job list to find the latest alarm job and set the RTC timer accordingly.
  3. RTC timer sends a signal to atd daemon at the scheduled time. Atd daemon scans the alarm job list to execute the scheduled job. The scheduled job can be: pop up an alarm window, play alarm sound and update the database tables accordingly. If the event is a repeating event, the next occurrence of the event will be calculated and will be added to the alarm job list.

 

3. todo