This 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:
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:
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--- ); }