Notification -Request Tutorial

diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita --- a/Symbian3/PDK/Source/GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,283 +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--- ); - }

+ + + + + +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