<?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 id="GUID-B7B7F611-BCA0-498F-BEC1-16B276F680D5" xml:lang="en"><title>Calling

Symbian Asynchronous APIs in Applications</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>When porting an P.I.P.S.-based C or C++ application on top of Symbian C++,

the developer may need to make use of Symbian asynchronous APIs. If asynchronous

APIs are made use of in an P.I.P.S. application, the application needs to

wait for the completion of the asynchronous API. This can be done in two ways:

 <ul>

<li><p>Wait for the asynchronous request to complete. This can be achieved

by making use of <codeph>User::WaitForRequest(iStatus)</codeph>; where <codeph>iStatus</codeph> is

the <codeph>TRequestSemaphore</codeph> used by the asynchronous API. </p></li>

<li><p>Call the asynchronous API in an active object, run an active scheduler,

and let the active scheduler wait for the asynchronous operation to complete. </p></li>

</ul></p>

<p><b>The problems with these approaches are: </b></p>

<p>The open source application would get blocked till the asynchronous operation

completes in the first approach. In the second approach, the active scheduler

would be running in a wait loop, checking for asynchronous API completion.

Even in this case, the P.I.P.S. application would not be able to perform any

other operations outside the active scheduler framework.</p>

<p>The asynchronous APIs could be called in a separate process, and the P.I.P.S.

application could communicate with this process by making use of the client/server

framework of Symbian or by making use of other P.I.P.S. IPC mechanisms. However,

making a different process for calling asynchronous APIs might pose a performance

hit.</p>

<p>One of the ways to solve these problems is to call the asynchronous APIs

in a separate thread.</p>

<p><b>Example:</b></p>

<codeblock xml:space="preserve">class CActiveThread:  public CActive

{

public: 

    enum TState

    {

    EInitialized = 0x0,

    EDoFirst = 0x1,

    EDoSecond = 0x2,

    EDoThird = 0x4,

    ECompleted = 0x8

    };

     // thread startup routine

    static int StartMyThread(void* thisptr);

    // leaving variant of the thread startup routine

    static int StartMyThreadL(void* thisptr);

    // Helper function to start the thread

    void StartThread();    

    // Do Function

    void DoFunction(TState aState );      

    // CActive Functions

    void RunL();

    void DoCancel();

    // Constructors and destructor      

    static CActiveThread* NewL(); 

    CActiveThread ();

    void ConstructL();

    ~ CActiveThread();      

private:    

    // Active Scheduler

    CActiveSchedulerWait *iWait;          

    // Command/State

    TInt iState;        	    

    TRequestStatus iThreadExitWait;	    

    // my thread handle

    RThread iActiveThread;    	    

    sem_t iSem;

};

</codeblock>

<p>The <codeph>StartThread</codeph> member function of <xref href="GUID-7968C6B4-3247-335A-845B-3D196E2EB14C.dita"><apiname>CActiveThread</apiname></xref> creates

the thread which runs the active scheduler. <codeph>StartMyThread</codeph> is

the entry point function for the new thread that starts an active scheduler

and sets up the clean up stack. To call an asynchronous function, <codeph>DoFunction()</codeph> needs

to be called with the corresponding state. The parent thread signals the child

thread using the child thread’s thread request semaphore. When the thread

request semaphore is signaled, the child thread wakes up, calls the corresponding

asynchronous API in <codeph>RunL()</codeph> based on the <codeph>iState</codeph> and

again goes back to the active scheduler wait loop.  </p>

<p>To synchronize between the parent thread and the child thread, a semaphore

can be used as shown in the following code snippet. </p>

<codeblock xml:space="preserve">CActiveThread* CActiveThread::NewL()

{

CActiveThread* self = new (ELeave) CActiveThread();

self->ConstructL();

return self;

}

CActiveThread::CActiveThread():CActive(EPriorityStandard),iState(EInitialized)

{       

}

void CActiveThread::ConstructL()

{  

// semaphore for Synching

sem_init(&iSem,0,0);  

}

void CActiveThread::StartThread()

{       

//Create Thread 

TInt err = iActiveThread.Create( KThreadName(),&CActiveThread::StartMyThread, KDefaultStackSize, NULL, (TAny*)this );

iActiveThread.Logon( iThreadExitWait );

iActiveThread.Resume();

sem_wait(&iSem );    

}

int CActiveThread::StartMyThread( void* ptr )

{

CActiveScheduler* scheduler = new (ELeave) CActiveScheduler();

CActiveScheduler::Install(scheduler);     

CTrapCleanup* pCleanup = CTrapCleanup::New();

TRAPD(err, StartMyThreadL(ptr));        

}

int CActiveThread::StartMyThreadL( void* ptr )

{        

CActiveThread *thisptr = (CActiveThread*)ptr;    

CActiveScheduler::Add(thisptr);

thisptr->iWait = new (ELeave) CActiveSchedulerWait();	    

thisptr->iState = EInitialized;

thisptr->iStatus = KRequestPending;

thisptr->SetActive();

sem_post( &(thisptr->iSem ));    

thisptr->iWait->Start();   

}

 void CActiveThread::RunL()

 {

 switch ( iState )

     {

     case  EDoFirst:

     // Call 1st asynchronous function

     break;

     case EDoSecond:

     // Call 2nd asynchronous function

     break;

     case EDoThird:

     // Call 3rd asynchronous function

     break;

     case ECompleted:

     iWait->AsyncStop();    

     return;			

     }

iStatus = KRequestPending;

SetActive();

// wake up the waiting thread

sem_post(&iSem);

}

void CActiveThread::DoCancel()

{    

}

void CActiveThread::DoFunction(TState aState )

{

iState = aState;

TRequestStatus *reqPtr = &iStatus;

iActiveThread.RequestComplete( reqPtr, KErrNone );

sem_wait(&iSem);

}    

CActiveThread::~CActiveThread()

{  

if ( iState != EInitialized )

    {

    iState = ECompleted;

    TRequestStatus *reqPtr = &iStatus;	

    iActiveThread.RequestComplete( reqPtr, KErrNone ); 

    User::WaitForRequest( iThreadExitWait);

    }    

sem_destroy(&iSem);

}

</codeblock>

<p><b>Using <xref href="GUID-7968C6B4-3247-335A-845B-3D196E2EB14C.dita"><apiname>CActiveThread</apiname></xref>:</b></p>

<codeblock xml:space="preserve">iMyAsyncIf = CActiveThread::NewL();   

iMyAsyncIf->StartThread();    

iMyAsyncIf->DoFunction(EDoFirst);

</codeblock>

<p><b>Limitations: </b></p>

<p>In this approach, only the parent thread communicates with the child thread.

There is no way for the child thread to communicate with the parent thread.

 </p>