EPOC   SDK Home Glossary Indexes Previous   Up

Using CBasicGsmRetrieveDetectedNetworks class


Contents

This section describes, by example, the use of the CBasicGsmRetrieveDetectedNetworks class.


Asynchronously retrieving detected networks

Section Contents


Overview

This topic describes how to create an active object wrapper around CBasicGsmRetrieveDetectedNetworks to asynchronously retrieve a phone’s 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.


The wrapper active object functions

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
          };

Constructing the wrapper active object — NewLC()

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

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 Start() function

The wrapper’s 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 wrapper’s RunL() function.

    void CExampleRetrieveDetectedNetworks::Start()
        {
        iRetrieve->Start(iStatus);  // start the search 
        SetActive();      // set the wrapper active object as active
        }      

The RunL() function

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()
          }

The DoCancel() function

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 object’s 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.


Using the wrapper active object

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 wrapper’s constructor is called, and the active object started. Upon completion of the active object, the wrapper’s 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();
Notes
EPOC       SDK Home Glossary Indexes Previous   Up