Playing with the N95 - The LBS API

So this tutorial will describe a simple App, very simple App, which just get the current location of the phone and write it on the view.
Why this tutorial ? because the Example App given in the S60 V3 FP1 SDK, LocationRefAppForS60, is a bit too sophisticated, according to me of course. It gave a lot information, Satellite informations, Module Info, etc.. which are not always useful for a basic use of the GPS, when what we want is just knowing where we are.

So let's begin :

Firsts things to know are the Classes we will use to obtain our location : RPositionServer and RPositioner.
What we can get from the SDK Help is :
- The RPositionServer It is used to make the primary connection to the location server. We use It with the Connect/Close methods, as others Symbian Server like RFs.
- After Connecting to the RPositionServer, we use a RPositioner to create a sub-session with the server for the purpose of obtaining the current position, useful methods are
- Open/Close, for connecting the RPositionner to the RPositionServer
- NotifyPositionUpdate which is is an asynchronous method for obtaining position updates, which use a TPositionInfoBase object for carrying Location Information and TRequestStatus.
- SetUpdateOptions which use a TPositionUpdateOptions defining how long we can wait to be positionned.

The use of a asynchronous method to obtain the location tell us that the use of an ActiveObject must be a good way of using the LBS API, so that's what we gonna do:
First we will create the Class CCActivePositioner which will :
- Initialize the LBS Stuff in is ConstructL method, RPositionServer and RPositioner initialization, SetUpdateOptions, and query a first Location.
- In its RunL method will check the state of its iStatus and if it's KErrNone will give the position to the view

here is this part of code :

void CCActivePositioner::ConstructL(CFirstGpsAppView *aView)
{
     iView = aView;

     // Connect to the position server
    TInt error = iPosServer.Connect( );
    
    // Open subsession to the position server
    error = iPositioner.Open(iPosServer);
    
    // Set position requestor
    error = iPositioner.SetRequestor( CRequestor::ERequestorService ,
         CRequestor::EFormatApplication , KRequestor );
   
   // Set update interval to one second to receive one position data per second
    TPositionUpdateOptions upOpt;
    upOpt.SetUpdateInterval(TTimeIntervalMicroSeconds(KUpdateInterval));
    upOpt.SetUpdateTimeOut(TTimeIntervalMicroSeconds(KUpdateTimeOut));
    upOpt.SetMaxUpdateAge(TTimeIntervalMicroSeconds(KMaxAge));
   
    // Set update options
    error =  iPositioner.SetUpdateOptions( upOpt );
     
    // Request first  position
    iPositioner.NotifyPositionUpdate(iPositionInfo,iStatus);

     // Set this object active
    SetActive()

As you see in this code it's just a base code, there's no error trapping which is not a good thing...

The constant KUpdateInterval,KUpdateTimeOut and KMaxAge are microseconds values, I've take them from the LocationRefAppForS60:

// CONSTANTS
//Second
const TInt KSecond = 1000000;
//Update interval
const TInt KUpdateInterval = KSecond;
//Update time out
const TInt KUpdateTimeOut = 15*KSecond;
//MaxAge
const TInt KMaxAge = 500000;

Rq : the SetRequestor is mandatory and tells the LBS who is requesting a Location.

Now the RunL method:

void CCActivePositioner::RunL()
{
	
	 
    switch ( iStatus.Int() )
    {
        // The fix is valid
        case KErrNone:
            {

            // We've got a Location, give it to the view
            iView->SetPos(iPositionInfo);
            // tell the view there's no error
            iView->SetErrorCode(0);
	   break;
            }
        default:
            // tell the view the error's code
        	iView->SetErrorCode(iStatus.Int());
    }

	// Request next position
       iPositioner.NotifyPositionUpdate( iPositionInfo, iStatus );
   	
       // Set this object active
   	SetActive();
}

View's SetPos and SetErrorCode method's have been created for giving the Location, or the error code, useful for debugging purpose, to the view.

That's All with the true LBS stuff, gaining the location of the mobile, Simple isn't it ?

Now I just want to show you how I've draw this location in the View, and remember it's a very simple App, So don't wait for a beautiful result
_

_LIT(KErrMsg,"Error: ");
_LIT(KPosMsg,"Pos: ");
_LIT(KDbgMsg,"Dbg: ");
_LIT(KPosSep,"/");
void CFirstGpsAppView::Draw( const TRect& /*aRect*/ ) const
    {
    // Get the standard graphics context
    CWindowGc& gc = SystemGc();
    // Gets the control's extent
    TRect drawRect( Rect());
    // Clears the screen
    gc.Clear( drawRect );
    
    
    //Prepare For Writing
    // In this example, we use one of the standard font styles
	const CFont* fontUsed = CEikonEnv::Static()->LegendFont();
	gc.UseFont(fontUsed);
	gc.SetPenColor(KRgbBlack);
    
    TBuf<128> msg;
    if (iErrCode != 0)
    {
    	msg.Append(KErrMsg);
    	msg.AppendNum(iErrCode);
   }
   else
  {
       TPosition pos;
  	iPos.GetPosition(pos);
  	TBuf<KDegreeLength> szLat;
  	TBuf<KDegreeLength> szLon;
  	GetDegreesString(pos.Latitude(),szLat);
  	GetDegreesString(pos.Longitude(),szLon);
  	msg.Append(KPosMsg);
    	msg.Append(szLat);
    	msg.Append(KPosSep);
    	msg.Append(szLon);
  }
  msg = msg;
  gc.DrawText(msg,drawRect.iTl+TPoint(0,20));
}

So here we saw that's I've just done a Draw Text with the error code, given by the CFirstGpsAppView::SetErrorCode if it's not null, or with the Pos info, set with CFirstGpsAppView::SetPos method, methods we saw in the previous RunL code.
We also use a GetDegreesString, which has been taken back from LocationRefAppForS60 another time. This methods translate the Microseconds value for Latitude and Longitude of the TPosition Object into a readable String.

So when you launch the App you've got the error Code "-33" which is drawn, it's a KErrTimedOut error, because the GPS hasn't found a good Location. Just wait a little, depending where you are, and you'll see your Location being drawn.

Ok that's all.
Don't forget to Add the Location Capability for your App in your mmp file, it's mandatory for accessing the GPS, And just do a more beautiful App than mine.

The source code is accessible here : http://www.newlc.com/files/FirstGps.zip
--
MarCo