![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
This section describes, by example, the use of the CBasicGsmRetrieveDetectedNetworks class.
Section Contents
This topic describes how to create an active object wrapper around CBasicGsmRetrieveDetectedNetworks to asynchronously retrieve a phones detected networks. The method described may be used in place of the combination of EnumerateDetectedNetworks() and GetDetectedNetworkInfo(), and eliminates the possibility of the detected network information changing before calling GetDetectedNetworkInfo().
The following section defines the wrapper class declaration and its functions, including NewLC(), RunL(), DoCancel() and Start(). It does not describe the destructor, which simply deletes the memory allocated to the CBasicGsmRetrieveDetectedNetworks object.
The second section demonstrates how the active object may be used. For more information on active objects, see Active Objects.
To use CBasicGsmRetrieveDetectedNetworks, clients should first create an active object wrapper for it, as shown below. The active object wrapper is defined in the same way as other active objects, with NewLC(), RunL() and DoCancel() functions. Start() activates the wrapper, through the CActive derived function SetActive().
class CExampleRetrieveDetectedNetworks : public CActive { public: static CExampleRetrieveDetectedNetworks* NewLC(RBasicGsmPhone& aPhone); ~CExampleRetrieveDetectedNetworks(); void Start(); private: CExampleRetrieveDetectedNetworks(RBasicGsmPhone& aPhone); void ConstructL(); void RunL(); void DoCancel(); private: CBasicGsmRetrieveDetectedNetworks* iRetrieve; // pointer to the wrapped search object RBasicGsmPhone iPhone; //the phone object to be passed into the // wrapped object };
CExampleRetrieveDetectedNetworks implements two phase construction using the function NewLC(). The function allocates enough memory for the new wrapper object and then pushes it onto the cleanup stack. The constructor, described in the following section, then initialises the new object.
CExampleRetrieveDetectedNetworks* CExampleRetrieveDetectedNetworks::NewLC(RBasicGsmPhone& aPhone) { CExampleRetrieveDetectedNetworks* r=new(ELeave) CExampleRetrieveDetectedNetworks(aPhone); //Allocate memory for new object CleanupStack::PushL(r); //Push new object onto cleanup stack r->ConstructL(); //second stage constructor return r; }
NewLC() then invokes the second stage constructor, ConstructL(), in which the wrapper is added to the active scheduler. A new search object is created and assigned to the iRetrieve member variable.
void CExampleRetrieveDetectedNetworks::ConstructL() { CActiveScheduler::Add(this); //add the object to the active schedular iRetrieve=CBasicGsmRetrieveDetectedNetworks::NewL(iPhone); //create CBasicGsmRetrieveDetectedNetworks object }
The constructor is empty, and serves only to initialise the new wrapper active object with a priority EPriorityNormal and an RBasicGsmPhone. The RBasicGsmPhone object is passed to the CBasicGsmRetrieveDetectedNetworks search object in the ConstructL() function.
CExampleRetrieveDetectedNetworks::CExampleRetrieveDetectedNetworks(RBasicGsmPhone& aPhone) : CActive(EPriorityNormal), iPhone(aPhone) {}
The wrappers start function calls CBasicGsmRetrieveDetectedNetworks::Start(), which initiates the search for detected networks. The function also sets the wrapper object as active, which tells the active scheduler to start monitoring the state of the search request. When the request completes, the active scheduler automatically calls the wrappers RunL() function.
void CExampleRetrieveDetectedNetworks::Start() { iRetrieve->Start(iStatus); // start the search SetActive(); // set the wrapper active object as active }
This function over-rides a pure virtual function in CActive. It is automatically called upon completion of the search.
Typically it would contain code to use the results of the completed search.
void CExampleRetrieveDetectedNetworks::RunL() { // some code to use the results of the search // using CBasicGsmRetrieveDetectedNetworks::RetrieveResults() }
This function is the part of the active object framework which defines the operations to be carried out when the wrapper active object is cancelled. In this example, the function calls the CBasicRetrieveDetectedNetworks objects cancel function, which in turn cancels the search for detected networks.
void CExampleRetrieveDetectedNetworks::DoCancel() { iRetrieve->Cancel(); }
To cancel the wrapper active object the client would call CExampleRetrieveDetectedNetworks::Cancel() , which invokes the public CActive function Cancel(). This would call the function DoCancel() above, and wait for it to complete.
The use of the wrapper is shown below. As with any ETel programming, the client must first create a server and connect to it. A TSY may then be loaded TSYs do not automatically support all, or any, of the function in the API. This example will fail if the TSY does not support CBasicGsmRetrieveDetectedNetworks functionality.
//Create a server session, connect, and load a TSY module RTelServer server; TInt ret = server.Connect(); ret=server.LoadPhoneModule(MODULE_NAME); //MODULE_NAME is a TSY which implements CBasicGsmRetrieveDetectedNetworks
The wrapper constructor, NewL(), takes an RBasicGsmPhone subsession as an argument. The next code fragment creates the subsession, and opens a named phone.
//Create a phone subsession, and open it with a named phone RBasicGsmPhone gsmPhone; ret=gsmPhone.Open(server,PHONE_NAME);
Using the wrapper active object is then very simple. The wrappers constructor is called, and the active object started. Upon completion of the active object, the wrappers RunL() function is automatically called. This function might contain the code which retrieves the search results into a CGsmDetectedNetworkResults.
// Example code for Asynchronous Retrieve Detected Networks CExampleRetrieveDetectedNetworks* testRetrieve=CExampleRetrieveDetectedNetworks::NewLC(gsmPhone); testRetrieve->Start(); // … other code would go here
When the program has finished the wrapper object must be removed from the cleanup stack and destroyed, as shown below. It is not necessary to destroy the CGsmDetectedNetworkResults object which stores the results of the search because it is owned by the wrapper and destroyed with it.
CleanupStack::PopAndDestroy(); // retrieve memory
Finally, the phone and server are closed.
//Close phone and server gsmPhone.Close(); server.Close();
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |