<?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(&amp;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-&gt;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-&gt;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>