Notification +Request Tutorial

diff -r 89d6a7a84779 -r 25a17d01db0c Symbian3/PDK/Source/GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/PDK/Source/GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita Fri Jan 22 18:26:19 2010 +0000 @@ -0,0 +1,283 @@ + + + + + +Notification +Request TutorialThis tutorial describes how to receive notification of the events +with the telephony API for applications. + + +

CTelephony can +notify the client applications about the status changes to the events like:

to detect inbound calls
to detect the phone +charger connection
battery charge information

The client applications can get the notification of the events that +contain a notification event, an information class and a cancellation +code. For example, the Voice +Line Status event describes that the client applications can receive +the notification when it changes. The event description contains:

+ + + +Item +Description + + + + +

CTelephony::EVoiceLineStatusChange

notification event

+ + +

CTelephony::TCallStatus

information class

+ + +

CTelephony::EVoiceLineStatusChangeCancel

cancellation code

+ + + +

+ + +create an instance of CTelephony +CTelephony* telephonyApi = CTelephony::NewL(); +CleanupStack::PushL( telephonyApi ); + + +create an instance of the class, passing it the pointer to CTelephony +CNotifyExample *exampleObject = new CNotifyExample( telephonyApi ); +CleanupStack::PushL( exampleObject ); + + +call the object's RequestNotification method to start +the request. This calls CTelephony::NotifyChange() +exampleObject->RequestNotification(); +pass the notification event and an empty instance of the information +class. This method starts an asynchronous operation that completes when the +requested notification event occurs +The new status will have been written into the TCallStatus object +that was given to NotifyChange() + + +you can see all the notification events in CTelephony::TNotificationEvent. +This also shows which information class is associated with each event + + +you can cancel a request for notification any time before the operation +finished. Do this by passing CTelephony::CancelAsync() the +cancellation code +

You should not request notification before the previous notification +request is either completed or cancelled. The notification request is started +after the active object is created, so there could not be a request. If you +are <bold>not</bold> sure that previous requests for that object have +completed, call theCActive::Cancel method before issuing +a new request:exampleObject->Cancel();exampleObject->RequestNotification(); +This will cancel any previous requests.

+ + +Voice line +status example

Here is an active object that detects a change in +voice line status. It doesn't do much when the voice line status changes; +it simply stores the new status values and then starts the next asynchronous +operation.

This is a basic Active +Object. You will need to know about active objects in order to use CTelephony's +notification abilities.

+ /* + Example CTelephony Notification + + This class uses the CTelephony API to get notification when a + phone's voice line status changes. + + This class is an active object. You will need to have knowledge of + active objects in order to understand this class. All active + object are derived from CActive. + + This program can be easily modified to get notification when other + events occur. + + See CTelephony::TNotificationEvent for a list of + events. + + */ + +#include <e32base.h> +#include <Etel3rdParty.h> + +class CNotifyExample : public CActive +{ + + public: + // Constructor/Destructor + CNotifyExample( CTelephony* aTelephony ); + + // Request voice line status change notification + void RequestNotification(); + + private: + /* + These are the pure virtual methods from CActive that + MUST be implemented by all active objects + */ + void RunL(); + void DoCancel(); + + private: + /* + A reference to a CTelephony, obtained with CTelephony::NewL() + or NewLC() + */ + CTelephony* iTelephony; + + /* + When the voice line status changes (and hence the asynchronous + operation completes) the new voice line status is written into + iLineStatus. Until this point, iLineStatus is not valid. + + If you change this class to get notification of other events, + then change this class. CTelephony::TNotificationEvent lists + the classes associated with each event. + */ + CTelephony::TCallStatusV1 iLineStatus; + CTelephony::TCallStatusV1Pckg iLineStatusPckg; +}; + + + + +/* + Default constructor. Pass it a reference to a CTelephony, created + with CTelephony::NewL() or NewLC() + */ +CNotifyExample::CNotifyExample(CTelephony* aTelephony): CActive( EPriorityStandard ), iTelephony( aTelephony ), iLineStatusPckg( iLineStatus ) + { + //default constructor + iLineStatus.iStatus = CTelephony::EStatusUnknown; + } + + + +/* + This method requests notification by calling + CTelephony::NotifyChange() to initialise an asynchronous operation. + Then it immediately calls CActive::SetActive to start the + operation. The operation completes when the notification event + occurs. + + In this case, we tell CTelephony to wait for the + CTelephony::EVoiceLineStatusChange notification event, hence the + event occurs when the voice line status changes. + + For other events, change the notification event in the call to + CTelephony::NotifyChange(). The CTelephony::TNotificationEvent + description all the notification events. + It also list the information class to + pass to CTelephony::NotifyChange(). The TCallStatus + class is associated with CTelephony::EVoiceLineStatusChange. + */ +void CNotifyExample::RequestNotification() + { + + /* + Panic if this object is already performing an asynchronous + operation + */ + _LIT( KNotifyExamplePanic, "CNotifyExample" ); + __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 )); + + iTelephony->NotifyChange( iStatus, CTelephony::EVoiceLineStatusChange, iLineStatusPckg ); + SetActive(); + } + + +/* + The active object's RunL method is called when the asynchronous + event completes. In this case, RunL is called when the voice line + status changes. When this occurs, the new voice line status is + written to the iLineStatus. iLineStatus was passed to + CTelephony::NotifyChange() when the asynchronous operation was + started. + + This is where you put your code to respond to your chosen + notification event. + + In all active objects, iStatus indicates whether the asynchronous + operation succeeded, failed, or is still in progress. KErrNone + indicates success, and hence the value in iStatus is valid. + */ +void CNotifyExample::RunL() + { + if( iStatus==KErrNone ) + { + /* + Insert code to respond to the change of voice line status + here. A typical use to answer a call if the voice line + status is 'ringing' (EStatusRinging) + + Remember that you must implement a RunError() method if + your code in RunL can leave. + */ + if( iLineStatus.iStatus == CTelephony::EStatusRinging ); // Answer call by calling 'AnswerIncomingCall()' + { + /* Request the next notification */ + iTelephony->NotifyChange( iStatus, CTelephony::ESignalStrengthChange, iLineStatusPckg ); + SetActive(); + } + } + } + +/* + Like all active objects, you must supply a DoCancel() method to + cancel the asynchronous operation. This must cancel a CTelephony + notification operation with CTelephony::CancelAsync. Give the method + the appropriate 'cancellation event' from those in 'TCancellationRequest' + + In this case, we are cancelling the "voice line status Change" event, + and so we need to supply the EVoiceLineStatusChange cancellation code. + If you change this class to respond to a different notification + event, remember to change the call to CTelephony::CancelAsync. + */ + +void CNotifyExample::DoCancel() + { + iTelephony->CancelAsync( CTelephony::EVoiceLineStatusChangeCancel ); + } +

Receive notification of other events

The previous examples +detect changes in voice line status. You can adapt this example for other +events as follows:

In the RequestNotification() method, +pass CTelephony::NotifyChange() the notification +event you want to detect, listed in CTelephony::TNotificationEvent. +Each event has an information class associated with it, which stores +the new information after it has changed. Pass NotifyChange() an +instance of the information class, too:
CNotifyExample::RequestNotification() + { + _LIT( KNotifyExamplePanic, "CNotifyExample" ); + __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 )); + + iTelephony->NotifyChange( iStatus, + ---Insert notification event--- + ---Insert packaged information class instance--- ); + SetActive(); + }
You will need to declare the information class instance +in the CNotifyExample's declaration.
Change the code in CNotifyExample::RunL that +handles the event.
Change the DoCancel method +to cancel the correct event. Insert the correct cancellation code from +those in CTelephony::TCancellationRequest:
CNotifyExample::DoCancel() + { + iTelephony->CancelAsync(---Insert cancellation code--- ); + }

+ \ No newline at end of file