How to Associate Data with an Alarm

As part of flexible alarm functionality users may wish to associate data with an alarm. For example, when an alarm expires the Alarm Control can display an image, play a sound/video file or open a URL. The class CCalContent holds in memory 8-bit data of any type, or a link to 8-bit data such as a URL.

To set up data associated with an alarm:

  1. Create a calendar entry such as an appointment or reminder: CCalEntry::NewL().

  2. Use CCalAlarm::NewL() to create a calendar alarm containing expiry time details. It is optional to set user-defined sound when adding extra data. The following combinations are:

    • No user-defined sound and CCalContent

    • User-defined sound and CCalContent

    • User-defined sound and no CCalContent

  3. Create the arbitrary data (CCalContent) to be played or displayed when the alarm expires. Two kinds of data may be added to an alarm. They are a URL and raw data (also known as inline data). Because it is recommended to use the smallest possible amounts of data to add to an alarm it is usually best to add files as URLs. Thus, an image file can be added simply as the URL of its address.

    The following code sample shows how to add a URL to an alarm:

     CCalContent* content = CCalContent::NewL();
     CleanupStack::PushL(content);
     . . .
     HBufC8* urlContentBuf = _L8("rtsp://radio.network.co.uk").AllocLC()
     HBufC8* mimetype = KMimeType("http").AllocLC();
        content->SetContentL(urlContentBuf, urlTypeBuf, CCalContent::EDispositionUrl);
        CleanupStack::Pop(urlContentBuf); // SetContentL takes ownership
        CleanupStack::Pop(urlTypeBuf);    //
        alarm->SetAlarmAction(content); //takes ownership
        CleanupStack::Pop(content);
        . . .
  4. Add the alarm to the entry using:

    entry->SetAlarmL(alarm);

    The entry does not take ownership of the alarm.

  5. Store the entry in the calendar database using CCalEntryView.

Data Retrieval

To retrieve data from an expired alarm the associated Calendar entry must be found, as well as the Calendar entry's alarm and data.

The last entry ID and the recurrence ID can be used to find the unique entry in the calendar databse. To get the alarm data once the proper entry has been found CCalEntry::Alarm() can be used. This returns a CCalAlarm object from which the CCalContent can be retrieved using the method CCalAlarm::AlarmAction(). This returns a CCalContent object.