<?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-B9079564-5E52-5221-AA2D-8B2EC2D79D21"><title>Asynchronous SendReceive() in an Agent</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>An agent plug-in may have to service an asynchronous request, for example when <xref href="GUID-D7457871-5361-3684-9A95-FBDB9C2689DD.dita#GUID-D7457871-5361-3684-9A95-FBDB9C2689DD/GUID-14972E77-6C62-3F62-AAD0-A4795EE7B2B3"><apiname>ContentAccess::CAgentManager::NotifyStatusChange()</apiname></xref> is called. If an agent plug-in makes an asynchronous <xref href="GUID-AB35D9C8-7317-30D1-BFB6-D57F6A9EF0A5.dita"><apiname>SendReceive()</apiname></xref> call to service the request, then it must ensure that any memory that is passed as an argument in the call is still valid, when the agent server that receives the call processes and uses the memory. </p> <p>There are two ways that this can be achieved: </p> <ul><li id="GUID-3D3319EA-E025-5DD1-A027-3073A40ABA5D"><p>storing a local heap copy of transient data, </p> </li> <li id="GUID-C7C74DBE-C75C-5E84-8CD7-9DAE9A03BC7C"><p>following the asynchronous call with a synchronous call. </p> </li> </ul> <section><title>Storing a local heap copy of transient data</title> <p>If the agent plug-in cannot guarantee that a variable to be passed in the asynchronous <xref href="GUID-AB35D9C8-7317-30D1-BFB6-D57F6A9EF0A5.dita"><apiname>SendReceive()</apiname></xref> call still be in scope when the agent server comes to access and use it, then the agent plug-in must store a local heap copy of the data and pass this in the call instead. It is the responsibility of the agent plug-in to maintain this heap memory and delete it when appropriate. Depending on how and when the agent server uses the memory, it may be safe to delete the memory after the asynchronous call has been accepted, or not until the asynchronous request has completed. </p> <p>For example, an agent plug-in could implement the <xref href="GUID-D7457871-5361-3684-9A95-FBDB9C2689DD.dita#GUID-D7457871-5361-3684-9A95-FBDB9C2689DD/GUID-14972E77-6C62-3F62-AAD0-A4795EE7B2B3"><apiname>ContentAccess::CAgentManager::NotifyStatusChange()</apiname></xref> API as illustrated below. Note that for this API, the agent plug-in can make no assumption about the scope of the descriptor passed to <codeph>aURI</codeph>. </p> <codeblock id="GUID-70BFC590-7864-5D4A-9C6A-659D2193E2FC" xml:space="preserve">void CTestAgentManager::NotifyStatusChange(const TDesC&amp; aURI, TEventMask aMask, TRequestStatus&amp; aStatus)

        {       

        HBufC* uri = aURI.Alloc();

        if(uri)

                {

                // store the heap variable in a local array

                iAsyncDataArray.Append(uri); // takes ownership of uri

                SendReceive(EManagerNotifyStatusChange, TIpcArgs(uri,aMask),aStatus);           

                }

        }</codeblock> </section> <section><title>Following the asynchronous call with a synchronous call</title> <p>Alternatively, the agent plug-in can use the variables that are in scope at the time of the asynchronous <codeph>SendReceive()</codeph> call if it makes a synchronous <codeph>SendReceive()</codeph> call afterwards, within the same function scope, as illustrated below. The synchronous message can be a 'no operation' in the agent server. </p> <codeblock id="GUID-E7D90116-D76E-5256-A213-DD35AFB66E80" xml:space="preserve">void CTestAgentManager::NotifyStatusChange(const TDesC&amp; aURI, TEventMask aMask, TRequestStatus&amp; aStatus)

        {       

        SendReceive(EManagerNotifyStatusChange, TIpcArgs(&aURI,aMask),aStatus);

        // this call doesn't have to be immediately after the asynchronous call, but within this function

        SendReceive(ENoOp,TIpcArgs(NULL));

        } 

</codeblock> <p>The synchronous call causes the message queue to be flushed into the agent server before the thread returns from the function and unwinds the call stack. The intention is that the agent server only completes the second (synchronous) message after receiving and doing initial processing of the first (asynchronous) message, which may include, for example, reading the uri descriptor. </p> <p>However, an obvious disadvantage of this pattern is that it incurs a second IPC call and so may degrade performance. </p> <p>Moreover, there are several caveats which must hold true in order for the pattern to work: </p> <ul><li id="GUID-9D298F83-FA66-5A83-B51C-0660DB2271D9"><p>The kernel delivers messages in the order that they are sent (this is currently true). </p> </li> <li id="GUID-21543BE4-282F-5027-BA29-A8840A775F99"><p>The agent server is guaranteed to finish processing the first message before completing the second message. This requires understanding of the agent server implementation. </p> </li> <li id="GUID-A6E9BAF2-C7CE-5FE1-A72F-FD49D4012860"><p>After initial processing of the first (asynchronous) message, the agent server does not need to access the memory supplied in the message again. This requires understanding of the agent server implementation. </p> </li> <li id="GUID-87FF3170-059C-5CC2-8E03-0A92D82194D9"><p>The synchronous call is a request that has no effect on the state of the agent server - a 'no operation' may or may not be possible. </p> </li> </ul> <p>For these reasons, this pattern must only be used as a last resort - for example, if the agent plug-in cannot store member data in its class for compatibility reasons. </p> </section> </conbody></concept>