Common mis-use and abuse of Symbian OS

 
Number 2:
------------

People putting calls to User::WaitForRequest(iStatus) in an active object.

DONT.

Number 4
-------------

How to return descriptors from functions.

First off, a mis-use: some of the descriptor classes are abstract, stop trying to declare a TDesC as a variable.

Now, how to use them in combination with functions:

If you are returning data from a function as a descriptor then:
- if its an entire descriptor and which will still exist while the caller uses it you should return const TDesC& or TDes& (if the caller is allowed to modify it).

- if you are returning data which is not an entire descriptor (i.e. it lives in a buffer or is part of another descriptor), which will still exist while the caller uses it, return TPtrC or a TPtr (if the caller is allowed to modify it).

- if the data has to be constructed, but has a known (not too big) maximum length, return a TBufC<> or TBuf<>

-if the data has to be constructed, and could have variable or long length, there are two basic options:

a) allocate an HBufC for the data and return HBufC*, the caller is then responsible for deletion of the object. Note: this requires allocation and free, which have a run time overhead.

b) have the caller pass a TDes& as a parameter and write back to that descriptor, ensuring that what happens if this is not "large enough" is well defined. This is expecially good for when the caller should specify how much data it wants returned--the descriptor's MaxLength() provides this.

Number 6
-------------

Back to active objects again, specifically cancelling. Here's some examples of what not to do that is seen frequently.

a) Calling DoCancel() directly - don't try to do this. Just call Cancel(), DoCancel() gets called automatically via Cancel()

b) Not calling Cancel() - if you've got an outstanding asynchronous request* and your active object is being deleted for example then you must call Cancel().


c) if (IsActive())
      Cancel()

There's no need to have this check that the object is active before calling Cancel(). It is safe to call Cancel() even if the active object isn't active, the active object base class code makes this check so there's no need for you to also.

d) Finally, you'd think this would be obvious but apparently not seeing as quite a few people do it, or rather don't do it:
Calling Cancel() but not adding any code to the body of the overridden DoCancel() to actually cancel anything.
If your DoCancel() function is empty how can any outstanding asynchronous request get canceled?


* However don't forget, some active objects are self scheduling.

Number 8
-------------

"My program hangs when I call CActiveScheduler::Start() and never reaches the next line  "

A lot of people who have never developed for a real-time environment have trouble initially getting their heads round the concepts involved. This is especially the case if they've previously only written simple programs where there is a sequence of steps and the code starts at the first step, goes through them all, gets to the last one then the program finishes. So they've previously only written a simple program, try to program on SYmbian and find out they have to use active objects and then it starts to fall apart (it not just Symbian, they'd have similar problems using threads or similar on any OS if they've never used them before).

If you're using an active object then you have to have an active scheduler installed. If you're writing an application i.e. a user interface then there will already be one installed which has been started and you shouldn't be messing around with them. If you're not writing a UI application (i.e. you're writing an exe for example) then you have to install and start an active scheduler yourself. This invaraibly starts to cause problems with newbies, consider this abbreviated pseudo code snippet and simpilfied explanation to consider why:



main()
{
CActiveScheduler* scheduler = new CActiveScheduler;
CActiveScheduler::Install(scheduler);
CActiveScheduler::Start();
CMyActive* active = CMyActive::NewL();
active->DoStuff();
}

They code this and then step through it in the debugger but after they get to CActiveScheduler::Start() nothing happens, it doesn't reach the next line and they don't understand why their program has hung.

The reason is because the call to CActiveScheduler::Start() effectivey shifts the paradigm of your program, you've now stopped working with baby programs where there is a simple sequence of steps of execution and its easy to follow, you've now jumped into the realm of real-time programming, where your code flow is now dictated by events external to your program so you have to change your way of thinking and make sure you properly understand how it works.


The above code won't work because once a call to CActiveScheduler::Start() is made then imagine that an infinite loop is being executed inside that function (actually it effectively is). Suppose this function were implemented as this:

CActiveScheduler::Start()
{
   while (true)
   {
   }
}

Now can you see why the main() code will hang and the next line never executed after the call to CActiveScheudler::Start()?


Of course its not as simple as that, but now that you can see why it would hang then we'll move onto showing a bit more of the code.


The code for the active schuduler does something like this (note this isn't actually exactly what happens but for the purposes of explanation assume that it is)

CActiveScheduler::Start()
{
    while (true)
    {
    if (something has happened that an active object is interested in == TRUE)
        YourActiveObject->RunL();
    }
}


The "something has happened that an active object is interested in" is set by another piece of code 'signalling' a TRequestStatus that you passed to it in your active object code.

So lets consider if in your active object you wanted to open a socket and the socket API is SomeSocketClass::Open(TRequestStatus& aStatus). Then
when the socket code has opened the socket this will result in the TRequestStatus being signalled which results in "something has happened that an active object is interested in"
becomeing set to TRUE and thus the active object's RunL() gets called.

Now lets assume the call to open the socket is in the following function:

CMyActive::DoStuff()
{
SetActive();
iSocket->Open(iStatus);
}


With the code as it is in main() you can see that "something has happened that an active object is interested in" will never be able to be set to TRUE because the call to open the socket
doesn't happen until after the call to CActiveScheuler::Start(),and thats stuck in an infinite loop. So you have to rearange your code as:

main()
{
CActiveScheduler* scheduler = new CActiveScheduler;
CActiveScheduler::Install(scheduler);
CMyActive* active = CMyActive::NewL();
active->DoStuff();
CActiveScheduler::Start();
TInt ImANumpty = 5;
}


Now the call to open the socket is made before we enter CActiveScheduler::Start()'s infinite loop.
Now the important thing to bear in mind is that when we are executing through the loop the socket code is also executing effectively in parallel in another part
of the operating system, and when it has opened the socket the "something has happened that an active object is interested in" turns
from being FALSE to being TRUE and as a consequence your active object's RunL() gets called.


People still have problems with the above code however, wondering why after they call CActiveScheduler::Start(), and even though their active object's
RunL() get's called they wonder why ImANumpty never gets called. Well its because CMyActive::RunL() is called but as we're still inside the infinite loop then calling
RunL() results in "something has happened that an active object is interested in" being set back to FALSE. So after RunL() is called we're back inside the infinite
loop forever unless (a) "something has happened that an active object is interested in" gets set back to TRUE again somehow or (b) we can break out of the loop somehow.
For (a) to happen you have to send another TRequestStatus to something, so in the case of the socket example it might be to send some data over the socket, so you're
code might be:

CMyActive::RunL()
{
SetActive();
iSocket->SendData(_L("the data to send"), iStatus);
}

When the data has been sent "something has happened that an active object is interested in" gets set to TRUE so RunL() gets called again.
Suppose now we're finished and don't to do anything else what then? We have to break out of the infinite loop, and this can be done with
CActiveScheduler::Stop(), so our RunL() code might look like:


CMyActive::RunL()
{
if (iState == ENotSentAnyDataYet)
   {
   SetActive();
   iSocket->SendData(_L("the data to send"), iStatus);
   iState = ESentData; 
   }
   else
      if (iState == ESentData)
          CActiveSchuduler::Stop();
}


The first time RunL() is called iSocket->SendData() gets called, the second time the RunL() is called CActiveScheduler::Stop() is called
which causes the infinite loop to stop and thus execution of CActiveScheduler::Start() finishes and thus the line TInt ImANumpty = 5; gets executed and the
program finishes.


important point: in the example code it shows execution returning to the main part of the program after the active scheduler has stopped. You would usually write this sort of code in an exe which is test code for example and which only runs for a short time and has a predetermined life span. Programs (servers, applications) on a mobile device aren't like that however, who knows when they will end. You have to stop thinking in terms of a program running and stopping once all its lines have been executed and start thinking in terms of a program running potentially for ever and it reacting to various events whenever they might occur.
There are not many times when you need to use an active scheduler, writing test code is one as mentioned, the other main one is if you write a server. For most users it is sufficient for you to not know they even exist.



8b
----
When to use the active scheduler: if you are writing an application i.e. a UI then the UI framework creates and starts an active scheulder for you, so you should have no need to create one of your own*.
If you are writing a DLL that uses active objects and your DLL is intended to be used by another component then again you shouldn't add an active scheulder to your DLL.
AN example when you'd use one are if you are writing an exe which makes use of active objects or uses components which use them.


*This, and indeed this whole posting, is a simplified overview of the active scheduler, you might be in situations where you need to add your own to have nested active schedulers. But thats a more advanced area  than the simplified overview given here

Number 11 - reasons why your SIS file may not install
--------------------------------------------------------------------

(These apply specifially to Symbian OS9.x/nokia 3.x. Some will apply to earlier versions, but many won't).


1) Your SIS might not be signed when it has to be. It might not be signed with the correct capabilites. It may not be signed with the correct certificate (Lots of rules here, see above for some of them).

2) Your certificate may have expired. Your device's date may not be correctly set so the device thinks the certificate has expired.

3) Your certificate may have been revoked.

4) You might be installing onto a test device and it doesn't have any root certificates installed.

5) If your SIS is signed with a developer certificate:
- are you installing to a device specified by the dev cert - they are for particular devices only?
- have you signed it with more than one dev cert?

6) Does your certificate contain the capabilites that the programs you are trying to install uses?

7) The format of SIS files has changed with Symbian OS9.x / Nokia 3.x. You might have built it using an old SDK and thus its format is out of date.

8 ) Your sis file contains exes and dlls built for the emulator and not for the device.

9) Your .pkg may contain typos in the names of installtion paths etc.

10) Your program uses Dlls etc. which aren't also in the SIS or on the device

11) There might not be enough memory or disk space to install the stuff.

12) The stuff in the SIS may already be installed on the device (there are rules about what can or can't be replaced)


13) You might be attempting to install to a forbidden directory.
- You shouldn't attempt to write to /sys/
- You should write your executables to /sys/bin/
- You shouldn't write to a private folder that isn't yours,  unless its to its import directory provided that it previously exists
- You should put things like .ini files, .mbs, data files in your  private folder
- You should put things like resources & bitmaps in /resource/

A private folder is /private/0x1234565789/, where 0x123456789 is the SID or 3rd UID of the program.
An import folder is /private/0x1234565789/import

14) Does your SIS have an SID (or 3rd uid) in the protected range (or a VID in the protected range. If you don't know what a VID is then you don't need to know). If it does it needs to be signed with an appropriate certificate.
For SIDs the protected range is 0-0x7fffffff and the unprotected range is 0x80000000-0xffffffff . For VIDs, the protected range is 0x00000001-0xffffffff and the unprotected range is 0x00000000.

15) Does your SIS file contain an exe with an SID (or 3rd UID) which is already being used on the device.