<?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-AE31B2A5-40BA-5FD4-9CCA-2CDF5B00DFDC" xml:lang="en"><title> Using

a Management Plane session to receive Access Point notifications: Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This tutorial shows how to register for Access Point notifications from

the Management Plane. Filters allow the notifications to be restricted to

certain Access Point fields. </p>

<p>The <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ</apiname></xref> API

has to be accessed through the <xref href="GUID-61E0CD76-A2E3-5066-84A8-146EECA8ADCD.dita">Sockets

Server</xref> client API, so you need to ensure that <filepath>esock.lib</filepath> is

included in the MMP file. </p>

<section><title>Procedure</title> <ol id="GUID-D9D1E509-2DB7-56FD-ACF2-B9F76B415AA5">

<li id="GUID-FAB284BB-919C-5B4F-AD78-A190E4032AA9"><p>Implement a class derived

from <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>MAccessPointNotificationObserver</apiname></xref>. </p> </li>

<li id="GUID-E9CE079D-5E47-5804-AC70-4754BC227CA0"><p>Construct a bundle of

type <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>ConnectionServParameterBundle</apiname></xref>.

The bundle specifies: </p> <ol id="GUID-3B94D198-D12D-5B32-B65B-60D4A5023243">

<li id="GUID-F6B10B9E-8A56-5173-BEC7-3525D6266FA2"><p>When to notify <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ</apiname></xref> about

the availability of Access Points. </p> </li>

<li id="GUID-3627A9A8-ECAB-5E77-9257-F9BE55252C1E"><p>What information the

client will receive in every notification. </p> </li>

</ol> </li>

<li id="GUID-C707D9E4-B15D-525F-906D-47E94E2415ED"><p>Call <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ::AccessPointNotification(const

                CConnectionServParameterBundle& aQuery,              

  MAccessPointNotificationObserver&amp; aObserver)</apiname></xref> to register for

notifications from the Management Plane. Specify <codeph>aObserver</codeph> as

the class from the first step, and <codeph>aQuery</codeph> as the bundle from

the previous step. </p> <ol id="GUID-D7FBCBD3-1F5D-5FA3-A90A-7EDF3D27C261">

<li id="GUID-224E8F20-E034-52C6-AD53-0DBEE08B8842"><p>The client application

receives the first notification with an empty bundle. </p> <p>For example,

the client receives an instance of <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>CConnectionServParameterBundle</apiname></xref> with

no <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>CParameterSetContainer</apiname></xref> 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 <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>AccessPointStatusQuery()</apiname></xref> ensures

that the client application has an accurate current view of the Management

Plane. </p> </li>

<li id="GUID-85DB2515-6099-58C5-8A55-C68D5DBC76E1"><p>Only one outstanding

notification is allowed for each <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ</apiname></xref> session.

If a second attempt is made then <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ::AccessPointNotification()</apiname></xref> returns <codeph>KErrInUse</codeph>. </p> </li>

</ol> </li>

<li id="GUID-0C30553B-DC7A-59B2-8829-A5E2F2ED9DDE"><p>Each notification is

received through a call to the <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>AccessPointNotification(CConnectionServParameterBundle*

                aResult)</apiname></xref> function of the class you derived from <codeph>MAccessPointNotificationObserver</codeph>. </p> <p>Each

notification includes a parameter bundle in <codeph>aResult</codeph>. 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. </p> </li>

<li id="GUID-DAF15ADB-B059-54A8-B8E4-B4D53448C296"><p>Call <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ::CancelAccessPointNotification()</apiname></xref>. </p> </li>

</ol> </section>

<section><title>Example Code</title> <p>The following is an example of Access

Point notification: </p> <codeblock id="GUID-65754B1A-75F0-56C8-BDCA-00238C3F818A" xml:space="preserve">

// 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);

    </codeblock> <p>Notification handlers are defined in the <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>RConnectionServ</apiname></xref> object.

If all the notification handlers are set up and ready, you must call <codeph>AccessPointNotification()</codeph> 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 <xref href="GUID-4AC100CB-D15E-35B0-9A68-FC2B49B747EA.dita"><apiname>XAccessPointGenericParameterSet</apiname></xref> derived

class. </p> <p>The code example continues as follows: </p> <codeblock id="GUID-5FE31600-F7D0-5BCC-9EE4-6BBA7988BA9D" xml:space="preserve">

/*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;</codeblock> </section>

</conbody></concept>