Using a Management Plane session to receive Access Point notifications: Tutorial

Procedure

1. Implement a class derived from MAccessPointNotificationObserver.

2. Construct a bundle of type ConnectionServParameterBundle. The bundle specifies:

   1. When to notify RConnectionServ about the availability of Access Points.

   2. What information the client will receive in every notification.

3. Call RConnectionServ::AccessPointNotification(const CConnectionServParameterBundle& aQuery, MAccessPointNotificationObserver& aObserver) to register for notifications from the Management Plane. Specify aObserver as the class from the first step, and aQuery as the bundle from the previous step.

   1. The client application receives the first notification with an empty bundle.

      For example, the client receives an instance of CConnectionServParameterBundle with no CParameterSetContainer as an argument. The receipt of this empty bundle is a signal to the client application that all relevant notifications have been set up and are active. At this point a call to AccessPointStatusQuery() ensures that the client application has an accurate current view of the Management Plane.

   2. Only one outstanding notification is allowed for each RConnectionServ session. If a second attempt is made then RConnectionServ::AccessPointNotification() returns KErrInUse.

4. Each notification is received through a call to the AccessPointNotification(CConnectionServParameterBundle* aResult) function of the class you derived from MAccessPointNotificationObserver.

   Each notification includes a parameter bundle in aResult. Ownership of this bundle is passed on this call. The client application must store this bundle until the bundle is no longer needed. The client application must delete the bundle once the bundle is no longer needed.

5. Call RConnectionServ::CancelAccessPointNotification().

Example Code

The following is an example of Access Point notification:

// Start the session as mentioned in starting a session
 
// create bundle (This bundle is owned by this class so the destructor of this class    
// must delete the bundle) 
iQueryBundle = CConnectionServParameterBundle::NewL();

// monitoring a specific Access Point
ASSERT(iKnownAccessPointId);

TAccessPointInfo apinfo;
apinfo.SetAccessPoint(iKnownAccessPointId);

// helper function to create basic query structure
//   for example, specification of the record to monitor the change
iQueryBundle->AddMatchConditionL(apinfo);

// specify the set of records to be monitored for change, for example,
//  the situation in which we want to be notified
TAccessPointStatusFilter availFilter;

// a) notify on all changes to this field
availFilter.Available(EAccessPointFlagMatchTrue);

// b) don’t notify on changes to these fields
availFilter.Configured(EAccessPointFlagIgnore);
availFilter.Restricted(EAccessPointFlagIgnore);
availFilter.Started(EAccessPointFlagIgnore);

iQueryBundle->AddMatchConditionL(availFilter);

// helper function to specify what we want to get for each Access Point
iQueryBundle->AddParameterSetToReturnL(XAccessPointGenericParameterSet::TypeId());

// start the notifications with this object as the handler
iConnServ.AccessPointNotification(*iQueryBundle,*this);

    

Notification handlers are defined in the RConnectionServ object. If all the notification handlers are set up and ready, you must call AccessPointNotification() with an empty bundle. This enables you not to miss any future events. You can now make a status query of the Access Point in which you are interested. At this point in time, you can delete the passed-in query bundle and later delete the bundle that contains changed Access Points. You can delete these whenever an Access Point enters or leaves the set of Access Points defined by the query parameters, or some other custom circumstances that are defined in a technology specific way in a particular XAccessPointGenericParameterSet derived class.

The code example continues as follows:

/*virtual*/
void CMyClass::AccessPointNotification(
CConnectionServParameterBundle* aNotification)
  {
  // process results.
  //  only expecting 1 Access Point record back as only 1 Access Point was in the query
  CConnectionServParameterSetContainer* parSetCtr
               = aNotification->GetParamSetContainer(0);
  ASSERT(parSetCtr); // very bad if nothing in bundle

  XAccessPointGenericParameterSet* genParamSet =
    XAccessPointGenericParameterSet::FindInParamSetContainer(parSetCtr);
  ASSERT(genParamSet); // we asked for this set back so fatal if
                // it’s not present in notification

  TUint apId = genParamSet->AccessPointInfo().AccessPoint();
  ASSERT(apId == iKnownAccessPointId);

  TAccessPointStatus availStatus = genParamSet->AccessPointStatus();

  if(availStatus.Availability() == ETrue)
    {
    ChangeIconToAvailable(); // your handler function
    }
  else if(availStatus.Availability() == EFalse)
    {
    ChangeIconToUnavailable();// your handler function
    }

  if(YouWantToStoreThisNotificationForLater())
    {
    iStoredNotifications.Append(aNotification);
    }
  else
    {
    delete aNotification;
    }

  if(BoredReceivingNotifications())
    {
    iConnServ->CancelAccessPointNotification();
    }
  }
//Later, in the destructor of this class the bundles must be deleted
delete iQueryBundle;
delete iStatusBundle;