week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
<?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-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6"><title> Attachment Support</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Overview</title> <p>A calendar entry has any number of attachments associated with it. These attachments are URI or file attachments. See the <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachment</apiname></xref> in-source documentation for more details about attachments. </p> <p>The <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachment</apiname></xref> class allows access to the attachment content itself and associated metadata. This can be either a URI (RFC 3986) or a file attachment, which must be specified on creation. A URI attachment requires a descriptor containing the URI. </p> <p>A file attachment can be specified as either a descriptor containing the binary data or as a file handle. Attachment data (URI and binary data) cannot be changed once an attachment has been created. This does not include metadata properties that are modifiable through the <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachment</apiname></xref> APIs. </p> <p>File attachments may also have only a content ID on creation. This is true in cases when a vCalendar or iCalendar (RFC 2445) is imported as part of a message. The content ID refers to the attachment file located elsewhere in the message. The attachment data must be set using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachment::SetResourceL()</apiname></xref> before the attachment can be stored. </p> </section> <section><title>Use Cases</title> <p>This section describes the following use cases: </p> <ul><li id="GUID-14E8B83C-6F63-56C4-A672-5A50B4CAD381"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-AC5D827C-359B-5F97-8F2C-7BC6B5AA3EB3">Add an attachment to a calendar entry from a file handle</xref> </p> </li> <li id="GUID-B415BB85-7942-51BE-A969-F9C55E9694E6"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-8529CEF3-8863-59F7-8CF6-365270F4E11D">Add an attachment to a calendar entry from binary data</xref> </p> </li> <li id="GUID-BBCD52DC-BEB9-5745-8D5F-B3D39135D4C5"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-505A8D56-F4BD-5606-85DF-2578F5BC3B94">Add a URI attachment to calendar entry</xref> </p> </li> <li id="GUID-6A40BA58-7B5B-5A0D-94B0-52B9590E4ADB"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-4527435C-4FB8-5A43-B873-01207745A191">Create an email message with a calendar entry and attachment</xref> </p> </li> <li id="GUID-5B9408E7-B79D-58D1-9D1F-39E3CA4C43D6"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-35BC5CE7-05B2-5BA9-91BD-07028A2BE37D">Receive an email message with a calendar entry and attachment</xref> </p> </li> <li id="GUID-ACAA17AB-EC1C-5200-A6DA-A0945B95029C"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-6FDD80AE-5AB7-5E52-814E-A7AD16FEECE3"> Fetch a calendar attachment as binary data</xref> </p> </li> <li id="GUID-08DA481D-E2BB-5520-923C-09C5BABC60BE"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-D6388AA9-4DAA-5E32-827C-0CC49C6F0646">Fetch a file handle of a calendar attachment</xref> </p> </li> <li id="GUID-D6803691-9933-5C00-BCAD-F04E6BE533FB"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-41FECE9A-E430-5220-9E6E-3CEB7EE3962C">Remove an attachment from a calendar entry</xref> </p> </li> <li id="GUID-D86300DF-B77E-50CA-9A2E-09D1F55FCA75"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-F3236480-45BF-51A0-9DA6-146AD1449F98">List all file attachments in order of size</xref> </p> </li> <li id="GUID-422B9A83-B4D8-5312-8D94-224DD6943BF2"><p><xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-ECB0F0B7-69FE-5CA5-819F-28742012F05C"> Do not export file attachments within vCalendar / iCalendar if they are above a certain size</xref> </p> </li> </ul> </section> <section id="GUID-AC5D827C-359B-5F97-8F2C-7BC6B5AA3EB3"><title>Add an attachment to a calendar entry from a file handle</title> <p>This use case is intended for a Calendar UI application if there is an option to attach a file to a calendar entry. To add a file attachment to a calendar entry, using a file handle: </p> <ol id="GUID-5A19E44A-71C6-5297-B1E7-BC29E2C8530C"><li id="GUID-FEA617A2-3CAF-5C68-9248-1DD5F50C17D6"><p>Fetch a calendar entry. </p> </li> <li id="GUID-CA8EFD63-B26F-5D10-9070-9E312530F19F"><p>Create a file of any type and obtain its file handle. </p> </li> <li id="GUID-590D4AED-E1DE-5008-A4CA-987FFF4FD8BC"><p>Add the file to the calendar entry (see example code below). </p> </li> <li id="GUID-DAEF0579-B54F-5CDC-9484-D2B646DE7C74"><p>Store the calendar entry. When the entry is stored the file is moved to the calendar store. </p> </li> </ol> <p> <b>Example code: </b> </p> <p>Preconditions: </p> <ul><li id="GUID-3E6BD495-2394-5E96-8E27-51206D9969FB"><p> <i>iFs</i> is an open session to the file server (RFs). </p> </li> <li id="GUID-2DAB2C25-F341-5DE3-B484-611F1CDBB4DF"><p> <i>attachmentFileName</i> is the file name of the attachment to be added (a descriptor). </p> </li> <li id="GUID-6A9A9709-3182-50C8-948F-55EEA818A040"><p> <i>label</i> is a label name to be given to the attachment (a descriptor). </p> </li> <li id="GUID-0244A06A-688B-5E25-ACF5-3AFB340CFFAF"><p> <i>calEntry</i> is a calendar entry (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref>) to which the attachment is added, on the cleanup stack. </p> </li> </ul> <codeblock id="GUID-DF927A16-1794-53AC-8206-DE3B5D6258A9" xml:space="preserve">
User::LeaveIfError(iFs.ShareProtected());
RFile fileHandle;
fileHandle.Open(iFs, attachmentFileName, EFileWrite);
CleanupClosePushL(fileHandle);
// create attachment and add to calendar entry
CCalAttachment* attachment = CCalAttachment::NewFileL(fileHandle);
CleanupStack::PopAndDestroy(&fileHandle);
CleanupStack::PushL(attachment);
// set attachment properties
attachment->SetLabelL(label);
...
calEntry->AddAttachmentL(*attachment); // calEntry takes ownership
CleanupStack::Pop(attachment);
</codeblock> <p>Note that the file selected is moved to the Calendar store and no longer exists in its current location. In effect the Calendar takes ownership of it. </p> </section> <section id="GUID-8529CEF3-8863-59F7-8CF6-365270F4E11D"><title>Add an attachment to a calendar entry from binary data</title> <p>This use case is intended for a messaging or sync application when importing a calendar entry that has an attachment as binary data. </p> <p>To add a file attachment to a calendar entry from binary data: </p> <ol id="GUID-245D6927-C45B-5F60-9AD0-C6BA40B029C8"><li id="GUID-A4E37DA8-5071-59F8-9CF9-8E9550B36075"><p>Fetch a calendar entry. </p> </li> <li id="GUID-9918F234-E8E6-593E-B12F-322D2B35B0AF"><p>Fetch the binary data of the attachment. </p> </li> <li id="GUID-C8FDE825-16D2-569C-BEC9-3B846418DF62"><p>Add the binary data to the calendar entry (see example code below). </p> </li> <li id="GUID-E373AF7C-EDFC-56E2-B0A0-60F0ACD9C609"><p>Store the calendar entry. When the entry is stored the attachment is added to the calendar store. </p> </li> </ol> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-06C3257A-BC26-59F7-851B-21DA97475FE2"><p> <i>binaryData</i> is the binary data of the attachment to be added (an 8-bit descriptor). </p> </li> <li id="GUID-03CC01F9-2719-52A2-B44F-119B632EF887"><p> <i>label</i> is a label name to be given to the attachment (a descriptor). </p> </li> <li id="GUID-618031F1-8F30-55C7-AB37-462324E881E4"><p> <i>calEntry</i> is a calendar entry (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref>) to which the attachment is added, on the cleanup stack. </p> </li> </ul> <codeblock id="GUID-12C5BFF1-F271-5624-AA8D-D5187C91CB4B" xml:space="preserve">CCalAttachment* attachment = CCalAttachment::NewFileL(binaryData);
CleanupStack::PushL(attachment);
// set attachment properties
attachment->SetLabelL(label);
...
calEntry->AddAttachmentL(*attachment); // calEntry takes ownership
CleanupStack::Pop(attachment);</codeblock> </section> <section id="GUID-505A8D56-F4BD-5606-85DF-2578F5BC3B94"><title>Add a URI attachment to calendar entry</title> <p>This use case could happen in a sync application when importing a calendar entry, or in a Calendar UI application if a user selects a URI to attach to a calendar entry. </p> <p>To add a URI attachment to a calendar entry: </p> <ol id="GUID-BA79150C-F82D-559B-8107-BF40338C4EA6"><li id="GUID-A00B4541-3178-5EF2-A312-54535E2390DC"><p>Fetch a calendar entry. </p> </li> <li id="GUID-B3DD72D0-7876-5D8E-8CD5-603804D7B9E5"><p>Get the URI as an 8-bit descriptor. </p> </li> <li id="GUID-85ADA54F-D158-5539-8DC9-64E06718F540"><p>Add the URI to the calendar entry (see example code below). </p> </li> <li id="GUID-5A7EF89C-678A-506E-946B-FFAA190B5027"><p>Store the calendar entry. </p> </li> </ol> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-01BC1013-62F9-5C88-9A1C-05AEADD28D1A"><p> <i>uriAttachment</i> is the URI link of the attachment to be added (an 8-bit descriptor). </p> </li> <li id="GUID-97B3673F-5455-5027-82C5-C68743034201"><p> <i>label</i> is a label name to be given to the attachment (a descriptor). </p> </li> <li id="GUID-130FB7D5-4F3D-5FA7-8F63-D35C1B75764B"><p> <i>calEntry</i> is a calendar entry (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref>) to which the attachment is added, on the cleanup stack. </p> </li> </ul> <codeblock id="GUID-1B7C279D-779E-5E45-B661-1D68F0A6E92A" xml:space="preserve">CCalAttachment* attachment = CCalAttachment::NewUriL(uriAttachment);
CleanupStack::PushL(attachment);
// set attachment properties
attachment->SetLabelL(label);
...
calEntry->AddAttachmentL(*attachment); // calEntry takes ownership
CleanupStack::Pop(attachment);</codeblock> </section> <section id="GUID-4527435C-4FB8-5A43-B873-01207745A191"><title>Create an email message with a calendar entry and attachment</title> <p>This use case is intended for all messaging applications when exporting a calendar entry that contains an attachment. </p> <p>In this case, the message must contain a vCalendar or iCalendar, and the attachment data itself. The location of the attachment data within the message is referenced by a content ID within the vCalendar or iCalendar. This is described in the MIME specification (RFC 2045). </p> <p>To create the email message: </p> <ol id="GUID-10186C27-7541-5119-AC85-265B0F95067A"><li id="GUID-093DA452-606D-5E48-8A76-6FF43EFA7982"><p>Fetch an entry from calendar store. </p> </li> <li id="GUID-FE977527-CB4B-5E5E-90F8-3B350E788DFC"><p>Fetch an attachment from the entry. </p> </li> <li id="GUID-F1C8841C-9BC0-5235-8BD1-84D92420CFE4"><p>Generate a content ID for attachment. </p> </li> <li id="GUID-BF477528-18BD-548C-9168-C10DC716A854"><p>Set the content ID on the calendar attachment object (see example code below). </p> </li> <li id="GUID-72243EAA-FBF2-54B1-9D54-FB31DF64C5FF"><p>Export the entry to a vCalendar or iCalendar. </p> </li> <li id="GUID-74A376D3-F76D-5F87-81A4-F9FAB3595534"><p>Add a vCalendar or iCalendar to the email message. </p> </li> <li id="GUID-D9B51660-8D1F-5A17-80E9-FE0248D1C695"><p>Extract the attachment as binary data from the calendar attachment object (see example code in <xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita#GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6/GUID-6FDD80AE-5AB7-5E52-814E-A7AD16FEECE3">Fetch a calendar attachment as binary data</xref>). </p> </li> <li id="GUID-15167A8C-DD47-55D0-932D-D3384C2D2B41"><p>Add the attachment to email message. </p> </li> </ol> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-D0366534-BA97-53FC-AF31-A9ECEDFFFCC0"><p> <i>calEntry</i> is a calendar entry (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref>) containing an attachment to be exported, on the cleanup stack. </p> </li> <li id="GUID-0B2BDC63-7317-5FCA-8557-1D9A1A1CDE54"><p> <i>attachIndex</i> is the index of the attachment in <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>calEntry</apiname></xref> to be exported (zero if the entry has only one attachment). </p> </li> </ul> <codeblock id="GUID-C6DD7405-CC61-5158-B67A-41E491436649" xml:space="preserve">
CCalAttachment* attachment = calEntry->AttachmentL(attachIndex);
if (attachment->FileAttachment() != NULL)
{
// generate a content ID for the attachment
...
// set the content ID on this attachment
attachment->FileAttachment()->SetContentIdL(contentId);
}
// export calEntry to create vCalendar / iCalendar
...</codeblock> </section> <section id="GUID-35BC5CE7-05B2-5BA9-91BD-07028A2BE37D"><title>Receive an email message with a calendar entry and attachment</title> <p>This use case is intended for all messaging applications when importing a calendar entry that contains an attachment. </p> <p>The message contains a vCalendar or iCalendar, and the attachment data. The location of the attachment data within the message is referenced by a content ID within the vCalendar or iCalendar. This is described in the MIME specification (RFC 2045). </p> <p>To extract a calendar entry and a file attachment from an email message: </p> <ol id="GUID-9D84270B-D782-51C2-8FD2-72C617EA82D2"><li id="GUID-3715F83B-1761-5986-8CC8-6A8D505E4A84"><p>Import the calendar entry from a vCalendar or iCalendar. </p> </li> <li id="GUID-E5764A61-9DEC-5360-AB62-7CE26CF43817"><p>Fetch the content ID of the entry’s attachment (see example code). </p> </li> <li id="GUID-646950A5-1177-55A5-ACF7-5B778637F50A"><p>Resolve this content ID and fetch the attachment as a file handle. </p> </li> <li id="GUID-FDE04657-AB83-53B9-AE8C-F1C44D394EF5"><p>Add the file handle to the calendar entry (see example code). </p> </li> <li id="GUID-A55DCF1E-90E4-5989-8BD7-831A3339B550"><p>Store the calendar entry. </p> </li> </ol> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-42F489F0-2805-58F3-AD10-BD7E31C9C0D1"><p> <i>calEntry</i> is a calendar entry which has been imported from a vCalendar or iCalendar. It is on the cleanup stack and has a file attachment. </p> </li> <li id="GUID-A4966061-8E3C-5169-8A98-0A32A1D35DE2"><p> <i>attachIndex</i> is the index of a file attachment in the calendar entry. </p> </li> </ul> <codeblock id="GUID-B7E20D86-FDB5-5557-9509-67A498AA46D0" xml:space="preserve">
CCalAttachment* attachment = calEntry->AttachmentL(attachIndex);
// check this is a file attachment with a content ID
if (attachment->FileAttachment() != NULL && attachment-> FileAttachment()->ContentId().Length() > 0)
{
RFile fileHandle;
// resolve the content ID to find the attachment file handle
...
// set the file handle on this attachment
attachment->FileAttachment()->SetResourceL(fileHandle);
}</codeblock> </section> <section id="GUID-6FDD80AE-5AB7-5E52-814E-A7AD16FEECE3"><title>Fetch a calendar attachment as binary data</title> <p>This use case is intended for a messaging or sync application when exporting a file attachment as binary data. </p> <p>To fetch an attachment from a calendar entry and extract the content as binary data: </p> <ol id="GUID-9ED4608B-D64A-5613-A933-E89E8C3B7D27"><li id="GUID-A99774F3-8B1B-56DB-822C-14B136496C83"><p>Fetch a calendar entry from the database. </p> </li> <li id="GUID-C1B3358F-3974-595B-9141-ED7C1B86D6D2"><p>Fetch the attachment’s binary data (see example code). </p> </li> </ol> <p> <b>Example code: </b> </p> <p>Preconditions: </p> <ul><li id="GUID-A506AA6E-E06B-5832-8D45-E13B31C389DD"><p> <i>calEntry</i> is a calendar entry which has been fetched from the calendar store, and placed on the cleanup stack. </p> </li> <li id="GUID-795928AD-52B9-5E34-8658-E0D6938A154C"><p> <i>attachIndex</i> is a valid index of an attachment on this entry. </p> </li> </ul> <codeblock id="GUID-3432B244-1050-569D-9975-FA982C6218BC" xml:space="preserve">
CCalAttachment* attachment = calEntry->AttachmentL(attachIndex);
if (attachment->FileAttachment() != NULL)
{
attachment->FileAttachment()->LoadBinaryDataL(); // fetches data
const TDesC8& KBinaryData = attachment->Value();
// KBinaryData contains the binary data of this attachment
...
}
else
{
const TDesC8& KUri = attachment->Value();
// KUri contains the URI of this attachment
...
}</codeblock> </section> <section id="GUID-D6388AA9-4DAA-5E32-827C-0CC49C6F0646"><title>Fetch a file handle of a calendar attachment</title> <p>This use case is intended for a calendar application to open an attachment file from a calendar entry. </p> <p>To fetch a file attachment from a calendar entry and open it: </p> <ol id="GUID-354116F5-A0B6-5221-A0DA-44863532B79F"><li id="GUID-2DCC5C29-3464-5D1A-8F83-DF6627CBF839"><p>Fetch the calendar entry from the database. </p> </li> <li id="GUID-38FF533D-54A2-5E74-857D-53F245900349"><p>Fetch the file handle (see example code). Note that the file handle is read-only. </p> </li> <li id="GUID-858BB3AE-6F8C-5843-B9AC-A46AEA84E0C3"><p>Open the file from its file handle. </p> </li> </ol> <p> <b>Example code: </b> </p> <p>Preconditions: </p> <ul><li id="GUID-4020EF55-CEC6-5934-B652-DCC68F652BEB"><p> <i>calEntry</i> is a calendar entry which has been fetched from the calendar store, and placed on the cleanup stack. </p> </li> <li id="GUID-113C0A61-6AE1-547B-A27D-9D2F7BD1158C"><p> <i>attachIndex</i> is a valid index of a file attachment on this entry. </p> </li> </ul> <codeblock id="GUID-C9435F74-6D7B-55AC-A3E2-52C0C5DD9CEF" xml:space="preserve">
CCalAttachment* attachment = calEntry->AttachmentL(attachIndex);
if (attachment->FileAttachment() != NULL)
{
RFile fileHandle;
attachment->FileAttachment()->FetchFileHandleL(fileHandle);
// fileHandle is a read-only file handle to this attachment
...
}</codeblock> </section> <section id="GUID-41FECE9A-E430-5220-9E6E-3CEB7EE3962C"><title>Remove an attachment from a calendar entry</title> <p>To remove an attachment from a calendar entry: </p> <ol id="GUID-9E7C9370-4CFD-521C-A128-DDB4166F5221"><li id="GUID-D6492233-C125-594E-93D7-5512823F3883"><p>Fetch a calendar entry with an attachment from the calendar store. </p> </li> <li id="GUID-3292823C-ED53-5B47-B677-180A21B57DB0"><p>Remove an attachment (see example code). </p> </li> <li id="GUID-80BED7A0-3CC4-5274-85F3-115E71676C4B"><p>Store the entry. The attachment is removed from the calendar store when the entry is stored. </p> </li> </ol> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-5AFDDE52-6468-5B77-AA26-71A90B0DA666"><p> <i>calEntry</i> is a calendar entry which has been fetched from the calendar store, on the cleanup stack. </p> </li> <li id="GUID-D91761FD-A1A0-52CA-8F74-CEF97F70DA88"><p> <i>attachIndex</i> is the index of the file attachment to be deleted on this entry. </p> </li> </ul> <codeblock id="GUID-680B3603-9B17-54FE-ABD2-3DD6367799E9" xml:space="preserve">
CCalAttachment* attachment = calEntry->AttachmentL(attachIndex);
calEntry->DeleteAttachmentL(*attachment);</codeblock> </section> <section id="GUID-F3236480-45BF-51A0-9DA6-146AD1449F98"><title>List all file attachments in order of size</title> <p>To find all file attachments in order of size to be displayed on a user dialog: </p> <ol id="GUID-E9CB4D8D-28BC-5F7A-BEE6-B69A77490B5A"><li id="GUID-DDE59FCA-9856-59B6-813B-E301FC51BAF4"><p>Create an attachment iterator. </p> </li> <li id="GUID-188A1BF6-F1DF-55AA-8035-47AB76C22326"><p>Fetch each attachment held by the iterator (sorted in order of size). </p> </li> <li id="GUID-097E77D3-E723-5594-A0F8-2DD0B446B01F"><p>Fetch details about all file attachments. </p> </li> <li id="GUID-D32AB8C8-D78F-5C32-9E4C-5EC06E6E8C75"><p>Display details in UI. </p> </li> </ol> <p> <b>Example code:</b> </p> <codeblock id="GUID-E1D7D56A-7A83-5D8A-A01A-6F78CDF104C5" xml:space="preserve">
CCalAttachmentIterator* attachmentIterator = iCalAttachmentManager-> FetchAttachmentsL(CCalAttachmentManager::ESortBySizeLargestFirst);
CleanupStack::PushL(attachmentIterator);
while (attachmentIterator->HasMore())
{
CCalAttachment* attachment = attachmentIterator->NextL();
CleanupStack::PushL(attachment);
// display attachment details
...
CleanupStack::PopAndDestroy(attachment);
}</codeblock> <p>Note that it may be useful to take ownership of the <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachment</apiname></xref> objects returned from the iterator if it is possible to carry out further actions. For example, if there is a delete option on the attachment dialog, the attachment metadata object is required to fetch the associated entry and remove the attachment. </p> </section> <section id="GUID-ECB0F0B7-69FE-5CA5-819F-28742012F05C"><title> Do not export file attachments within vCalendar and iCalendar if they are above a certain size</title> <p>This use case is intended for sync applications. </p> <p>When file attachments are exported in a vCalendar by AgnVersit, they are always exported as binary data unless the ‘do not export inline’ flag is set. This flag may be set on any attachment. </p> <p>AgnVersit does not make any checks to see if a file is too big to be exported. However, if an out of memory error occurs while exporting binary data, the binary data is ignored as if the ‘do not export inline’ flag had been set. </p> <p>To find all file attachments above a certain size and flag these attachments as ‘do not export inline’: </p> <ol id="GUID-E72D34B6-ED1C-51C2-8B72-30A180957E36"><li id="GUID-7EB197D4-B4C8-57EE-A6D2-9209FB4D48A2"><p>Fetch details about all file attachments, sorted in order of size. </p> </li> <li id="GUID-496E9346-6037-50EB-A3F2-826BE463717C"><p>If the file attachment is greater than a certain size, modify its attributes so it is not exported inline. </p> </li> <li id="GUID-E688975F-F388-51CA-B30D-E0ABAF22A005"><p>Update the calendar entry with this modified attachment metadata. </p> </li> <li id="GUID-48F125E0-7FDA-5940-9992-420D2F38265D"><p>Store the entry. </p> </li> </ol> <p>Note that it is possible to set the ‘do not export inline’ flag for one synchronisation only. In this case, the attachment’s flag can be set on the entry immediately before exporting, without storing the entry in the database. This ensures that other synchronisation clients are unaffected. This approach does not require the <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalAttachmentManager</apiname></xref>, instead the client needs to check all entries for their attachments over a certain size. </p> <p> <b>Example code:</b> </p> <p>Preconditions: </p> <ul><li id="GUID-FAF08BFD-AE10-5572-9E15-E1AA8160B2F9"><p> <i>KSizeThreshold</i> is the size in bytes above which an attachment must not be exported. </p> </li> <li id="GUID-EF1FEC9A-F234-594E-815A-65D18D0B7F22"><p> <i>iCalAttachmentManager</i> is the open calendar attachment manager. </p> </li> </ul> <codeblock id="GUID-BDEE1742-A44C-5E98-B16C-7512522B8A66" xml:space="preserve">
// fetch file attachments in an iterator in size order, largest first
CCalAttachmentIterator* attachmentIterator = iCalAttachmentManager-> FetchAttachmentsL(CCalAttachmentManager::ESortBySizeLargestFirst);
CleanupStack::PushL(attachmentIterator);
while (attachmentIterator->HasMore())
{
// fetch next attachment from iterator
CCalAttachment* attachment = attachmentIterator->NextL();
CleanupStack::PushL(attachment);
if (attachment->FileAttachment() != NULL)
{
// get the attachment size
const TInt KAttachSize = attachment->FileAttachment()->Size();
if (KAttachSize < KSizeThreshold)
{
// if an attachment whose size is smaller than the threshold is reached, stop iterating – attachments are in size order so there are no more attachments which are greater than the threshold
break;
}
else
{
// this attachment has a size greater than the threshold
RArray<TCalLocalUid> localUids;
CleanupClosePushL(localUids);
// get the IDs of entries associated with this attachment
iCalAttachmentManager->EntriesReferencingFileAttachmentL (localUids, *attachment);
for (TInt I = 0; I < localUids.Count(); ++I)
{
// fetch each entry associated with the attachment (usually there is only one)
CCalEntry* calEntry = iEntryView->FetchL(localUids[i]);
CleanupStack::PushL(calEntry);
// modify the attachment’s metadata in order not to export inline
calEntry->DeleteAttachmentL(*attachment);
attachment->ClearAttribute(CCalAttachment::EExportInline);
calEntry->AddAttachmentL(*attachment);
// store the entry with the modified attachment
...
CleanupStack::PopAndDestroy(calEntry);
}
CleanupStack::PopAndDestroy(&localUids);
}
}
CleanupStack::PopAndDestroy(attachment);
}
CleanupStack::PopAndDestroy(attachmentIterator);</codeblock> </section> <section><title>Implementation Considerations </title> <p> <b>Error condition handling: </b> See in-source documentation for expected error codes. </p> <p> <b>Performance: </b> Creating large attachments results in a lot of memory being taken up. However, storing entries containing these attachments is only slightly slower than storing entries without attachments because the entire attachment is not passed over IPC. File handles are passed over IPC instead. </p> <p> <b>Security: </b> The use of file handle transfer ensures that no user can modify an attachment in the calendar store. Users need ReadUserData capability to read attachment data, which is in a read-only format. </p> </section> </conbody></concept>