<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-8FDCABBB-AD6D-513D-9FBF-631DC1846D20"><title>How to Associate Data with an Alarm</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>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 <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref> holds in memory 8-bit data of any type, or a link to 8-bit data such as a URL. </p> <p>To set up data associated with an alarm: </p> <ol id="GUID-3E86B9B9-95CF-5112-B5DA-5F8F201F7FC6"><li id="GUID-C5771F4B-BA6C-5BE8-A87C-2E1210EB537D"><p>Create a calendar entry such as an appointment or reminder: <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-AAFDB9B2-260A-3CB4-BD6E-058A04FEC327"><apiname>CCalEntry::NewL()</apiname></xref>. </p> </li> <li id="GUID-0A33163C-1C39-5F6E-B0EB-3DE7B4E3DE08"><p>Use <xref href="GUID-211D3640-9862-3F78-98FC-9793578117A9.dita#GUID-211D3640-9862-3F78-98FC-9793578117A9/GUID-77A0F5D8-364A-34C9-BF51-AAAE2A0E92F4"><apiname>CCalAlarm::NewL()</apiname></xref> 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: </p> <ul><li id="GUID-24FF19EC-E103-581F-A575-E15DFCBF926B"><p>No user-defined sound and <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref>  </p> </li> <li id="GUID-A739BB2C-6094-5AAC-B350-FAD97E4A5474"><p>User-defined sound and <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref>  </p> </li> <li id="GUID-11C78A05-98C6-5EF8-99B9-75024005917C"><p>User-defined sound and no <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref>  </p> </li> </ul> </li> <li id="GUID-6E5B9A2C-E4C1-50E6-83E3-4091416FF22B"><p>Create the arbitrary data (<xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref>) 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. </p> <p>The following code sample shows how to add a URL to an alarm: </p> <codeblock id="GUID-0D5AB6AF-1284-5A04-8DBC-0DEF0ACCDA0C" xml:space="preserve"> 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);

    . . .</codeblock> </li> <li id="GUID-93ACF59E-61EB-5306-9444-00FC3EBF1769"><p>Add the alarm to the entry using: </p> <codeblock id="GUID-DED01561-9750-5010-81EA-87D4C27A1B6A" xml:space="preserve">entry-&gt;SetAlarmL(alarm);</codeblock> <p>The entry does not take ownership of the alarm. </p> </li> <li id="GUID-DB8C4145-5687-5281-A942-5F9012A748DF"><p>Store the entry in the calendar database using <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita"><apiname>CCalEntryView</apiname></xref>. </p> </li> </ol> <section><title>Data Retrieval</title> <p>To retrieve data from an expired alarm the associated Calendar entry must be found, as well as the Calendar entry's alarm and data. </p> <p>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 <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-CBF85531-8FBE-3BA1-AB0B-F780653C5ABF"><apiname>CCalEntry::Alarm()</apiname></xref> can be used. This returns a <xref href="GUID-211D3640-9862-3F78-98FC-9793578117A9.dita"><apiname>CCalAlarm</apiname></xref> object from which the <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref> can be retrieved using the method <xref href="GUID-211D3640-9862-3F78-98FC-9793578117A9.dita#GUID-211D3640-9862-3F78-98FC-9793578117A9/GUID-B7EB9319-E22D-3C6B-9E3A-F7A0841E6DC8"><apiname>CCalAlarm::AlarmAction()</apiname></xref>. This returns a <xref href="GUID-A4B96729-C74A-3E0A-9906-2CDED08574AC.dita"><apiname>CCalContent</apiname></xref> object. </p> </section> </conbody></concept>