<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-91ED5F9C-216D-539D-B4D0-E6F2E087773E" xml:lang="en"><title>Creating

attachments to messages</title><shortdesc>The messaging framework allows you to create attachments to be

added to messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context id="GUID-AD25E60B-49ED-57AB-B727-6A6CB5EBE730"><p>Attachments to

messages are created as empty files before they are filled and added to a

message. </p> </context>

<steps id="GUID-C3909B48-18F8-5CCE-8661-EEBB64DDCF28">

<step id="GUID-0257AD84-72B4-5C9F-B7B2-D0092F847AB7"><cmd/>

<info>Create an active object implementation. All the <xref href="GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD.dita"><apiname>MMsvAttachmentManager</apiname></xref> functions

that modify attachments for an entry are asynchronous, so a request must be

called with an active object implementation. </info>

<stepxmp><codeblock id="GUID-4667A5C6-7A2C-539B-9D86-8807032D0294" xml:space="preserve">void CFoo::CreateAttachmentL(CMsvEntry&amp; aEntry )

    {

    _LIT(KFileName, "textfile.txt");

...

    // Wait for request to complete

    User::WaitForRequest(status);

    // Write to the file at the current offset within the file. 

    User::LeaveIfError(file.Write(_L8("text file as attachment")));

    CleanupStack::PopAndDestroy(&file);

    CleanupStack::PopAndDestroy(store);

    }

</codeblock> </stepxmp>

</step>

<step id="GUID-9F363DA2-9281-595A-B115-FD63DDD05D10"><cmd>Get the details

of the message to which you want to add an attachment using <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita#GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49/GUID-1864B96D-CB22-3EE1-8E73-023F12C68CB0"><apiname>CMsvEntry::EditStoreL()</apiname></xref>. </cmd>

<stepxmp><codeblock id="GUID-223B5F86-1D47-5F9A-97A4-45B6B28B277A" xml:space="preserve">    CMsvStore* store = aEntry.EditStoreL();

    CleanupStack::PushL(store);

</codeblock> </stepxmp>

<info>This function returns <xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita"><apiname>CMsvStore</apiname></xref> in writable mode. </info>

</step>

<step id="GUID-880AB139-CD3E-5283-A67B-0901482BC7B3"><cmd>Get an <xref href="GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD.dita"><apiname>MMsvAttachmentManager</apiname></xref> attachment

manager for the message entry, using <xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita#GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE/GUID-73CE27F3-855B-3F87-AE11-4B4F2B8F8825"><apiname>CMsvStore::AttachmentManagerL()</apiname></xref>. </cmd>

<stepxmp><codeblock id="GUID-5719D172-1127-557A-AE3D-C138EFEFAF67" xml:space="preserve">    MMsvAttachmentManager&amp; attManager = store-&gt;AttachmentManagerL();

</codeblock> </stepxmp>

</step>

<step id="GUID-3D26FDBB-2E55-52BA-AB2A-98AB4B72A2B7"><cmd/>

<info>Create a new attachment attributes object using the <xref href="GUID-8C2B9B89-D6B7-3622-AF26-658F53BCB70F.dita#GUID-8C2B9B89-D6B7-3622-AF26-658F53BCB70F/GUID-CB0C9E14-A0D3-340A-929D-8B2C3BC11300"><apiname>CMsvAttachment::NewL()</apiname></xref> function. </info>

<stepxmp><codeblock id="GUID-D0C29614-2C96-59C0-8B33-3161764637EA" xml:space="preserve">    // create a new attachment attributes object

    CMsvAttachment* attachment = CMsvAttachment::NewL(CMsvAttachment::EMsvFile);

    CleanupStack::PushL(attachment);

    // set attachment file name

    attachment->SetAttachmentNameL(KFileName());

</codeblock> </stepxmp>

</step>

<step id="GUID-0171595B-14E9-5F29-A0A0-ED7C7B2F05F6"><cmd/>

<info>Initialise a file handle. </info>

<stepxmp><codeblock id="GUID-678974F9-CF55-5D2C-A870-06FD0466B29C" xml:space="preserve">    // A file handle

    RFile file;

    CleanupClosePushL(file);

    TRequestStatus status;

</codeblock> </stepxmp>

</step>

<step id="GUID-1136ACD3-307E-5C19-80BD-80AF901F8F7C"><cmd/>

<info>Create a new attachment using the <xref href="GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD.dita#GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD/GUID-DA2E53AD-EC8F-38F9-8D5C-03AC356E7B64"><apiname>MMsvAttachmentManager::CreateAttachmentL()</apiname></xref> function. </info>

<info>The <xref href="GUID-F9A3E3A7-664B-3684-89EA-3DD5CB975AF1.dita"><apiname>CreateAttachmentL()</apiname></xref> function creates a new empty

attachment file and returns an open writable file handle to the empty attachment

file in the Message Store. You must pass an uninitialised file handle. The

file handle cannot be used until the asynchronous request completes successfully.

If the request is successful, the file handle is opened for writing. </info>

<stepxmp><codeblock id="GUID-448F438F-AD34-5A31-A79D-ED6DE2004E0A" xml:space="preserve">    // CreateAttachmentL API will return an open writable file handle 

    // to an empty attachment file in the message store. 

    attManager.CreateAttachmentL(KFileName, file, attachment, status);

</codeblock> </stepxmp>

</step>

<step id="GUID-3C167920-96C7-5081-AE58-8A65E68931A9"><cmd/>

<info>Commit the store. </info>

<stepxmp><codeblock id="GUID-DEAA9B94-C265-5536-A984-E07B5EC60DD7" xml:space="preserve">    // Commit the store

    store->CommitL();

</codeblock> </stepxmp>

</step>

</steps>

<result id="GUID-F5F40B70-71ED-5150-A5A8-602FB2134C87"><p>The result of creating

an attachment is an empty file with a handle opened for writing. </p> </result>

<postreq id="GUID-52A82DB6-ECA7-5910-A0E7-FC5726F280CE"><p>You can now add

the attachment to a file and retrieve and modify it. </p> </postreq>

</taskbody><related-links>

<link href="GUID-1963A487-D6A7-4225-8D0C-EC5FAB746854.dita"><linktext>Attachment

Tutorial</linktext></link>

<link href="GUID-54AB166A-8B24-5065-92AD-5FC1BF3ED89C.dita"><linktext>Messaging

Framework Overview</linktext></link>

</related-links></task>