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.