LTSY -for Dispatcher Tutorial

diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-6E5E74E6-4476-5ACE-8A37-93DB0E7999C6.dita --- a/Symbian3/PDK/Source/GUID-6E5E74E6-4476-5ACE-8A37-93DB0E7999C6.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-6E5E74E6-4476-5ACE-8A37-93DB0E7999C6.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,225 +1,225 @@ - - - - - -LTSY -for Dispatcher Tutorial This topic describes how to implement a Licensee TSY for the Common -TSY with the Dispatch layer. -

Developers implementing -the LTSY can start from the skeleton code at ../ctsydispatcher/ltsyskeleton_using_dispatcher/...

The -skeleton is a list of source files with empty implementations. The skeleton -is for guidance and the implementation depends on the requirements of the -handset manufacturer. The skeleton code contains mock test code for testing -purpose. The skeleton code can be conditionally recompiled to remove the calls -into the Mock test component, thus allowing the developer to run the existing -tests against the actual LTSY implementation they are creating with minimal -changes. Check the header file comments for mock test code. The request handlers -that must be implemented by the LTSY are declared in mltsydispatchcallcontrolinterface.h.

- - -Start developing the LTSY from the skeleton code - - -Implement the different interfaces based on functional units. -The required interface implementations depend the baseband. - - -The interfaces are split into different functional units. Implement -a call-back function for every asynchronous dispatcher call. - - -If the methods used to receive the baseband notification use blocking -API calls, create a new thread to receive the notification information in -the LTSY. - - -Remove the Symbian test macros - - -The LTSY must map the baseband error codes to Symbian error codes defined -in the header files exterror.h and gsmerror.h. - - -LTSY example

A -sample LTSY implementation to dial a voice call is given below.

Implementing MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL() interface:

-virtual TInt HandleDialVoiceReqL(RMobilePhone::TMobilePhoneALSLine aCallLine, -RMobilePhone::TMobileAddress&amp, aDialledParty, -RMobileCall::TMobileCallParamsV1&amp, aCallParamsV1, TBool aIsIsvCall, -RMobileCall::TCallParamOrigin aCallOrigin) = 0; - -/** - * The CTSY Dispatcher shall invoke this function on receiving the EEtelCallDial - * request from the CTSY for dialling a voice call. - * - * It is a request call that is completed by invoking - * CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp - * - * Implementation of this interface should - * dial the requested voice call and complete the callback to indicate - * that an attempt to dial the call has been made. The callback function is used - * to indicate the outcome of this attempt to initiate the dialling process. - * - * @param aCallLine The line to use to dial the call. This parameter can have - * one of two possible values RMobilePhone::EAlternateLinePrimary to use the - * primary voice line or RMobilePhone::EAlternateLineAuxiliary to use the - * auxiliary voice line. - * - * @param aDialledParty Details about the dialled party including the phone - * number to dial. - * @param aCallParamsV1 The call parameters of the call to dial. If aIsIsvCall - * is set to ETrue, only the field RMobileCall::TMobileCallParamsV1::iIdRestrict - * and RMobileCall::TMobileCallParamsV1::iAutoRedial fields are valid. - * - * @param aIsIsvCall Indicates whether the call originated from a third party - * application which would have used the CTelephony class to dial the call. - * This information is provided in case the LTSY wishes to do special handling - * for third party calls, for example, not allow third party applications to - * place emergency calls. See also - * MLtsyDispatchCallControlQueryIsEmergencyNumber::HandleQueryIsEmergencyNumberSyncL - * See also: CTelephony::DialNewCall and RMobileCall::DialISV - * - * @param aCallOrigin The origin of the dial request. For example, whether the dial came from an Etel client or the SIM or another source. - * - * @return KErrNone on success; KErrNotSupported if the LTSY does not support handling of this request or another error code - *indicating the failure otherwise. - */ -

Call back function to complete the call dial request:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp( - TInt aError, TInt aCallId) - -/** - * Callback function to be used by the Licensee LTSY to complete a pending - * MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL - * - * When a dial attempt is made via the above mentioned interface, the LTSY has the - * responsibility of allocating a unique Call ID to the call. For more - * information, see the documentation on aCallId below. - * - * @param aError The error code to be returned to the CTSY Dispatcher by the LTSY - * indicating the outcome of the attempt to dial the requested call. This should - * be KErrNone if the dialling process could be started successfully. Otherwise - * another error code to indicate the failure should be returned. - * - * @param aCallId The call ID of the call that the dial attempt refers to which - * has been allocated by the LTSY. This should be a number between 1 and - * KMaxCallIdValue and should be unique across all call modes (voice, data etc.). - * For example, if a request for a voice call is made and the LTSY allocates - * this call an ID of 1 and a request for a data call is requested, the LTSY - * should allocate a Call ID which is not the same as that already allocated for - * the first voice call. - * - */ -

To indicate call status change notifications, use the following -callback:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlNotifyCallStatusChangeInd( - TInt aCauseCode, TInt aCallId, RMobileCall::TMobileCallStatus aMobileCallStatus) - -/** - * Used by an LTSY to indicate to the CTSY that there has been a change in the - * status of a call. For example, if the CTSY has previously made a dial request - * to make a voice call, the LTSY can call this API to notify the CTSY - * of progress of the call through the dialling, connecting and connected states. - * - * The aCauseCode parameter should be used to indicate the reason for the change - * in status of a call. - * - * In the case of a call going idle (aMobileCallStatus = RMobileCall::EStatusIdle) - * specific cause codes need to be returned to the Common TSY to indicate - * specific causes of status changes: - * - * To indicate that an active call has been released normally by either party, - * set aCauseCode = KErrGsmCCNormalCallClearing. - * - * To indicate that a mobile originated call that is being dialled has gone - * idle because the remote party has rejected the call, set - * aCauseCode = KErrGsmCCCallRejected or another error code (which is != KErrNone) - * to indicate the reason for rejection. - * - * If a mobile originated call is being dialled and the user cancels dialling, - * causing the call to go idle, set aCauseCode = KErrGsmCCNormalCallClearing. - * - * When an incoming call goes idle because the client has rejected it - * (done using RCall::HangUp on the ringing call), set - * aCauseCode = KErrGsmCCUserBusy. - * - * @param aCauseCode The cause of the change in call status. - * - * @param aCallId The Call ID of the call whose status has changed. - * - * @param aMobileCallStatus The new status of the call refered to by aCallId. - * - * @see RMobileCall::NotifyMobileCallStatusChange - */ - -

Implement other functions supported by the baseband and it -is the responsibility of the LTSY to return appropriate error code in the -call back function if it fails to establish a call.

Build and run the -components.

Unzip code to your target -disk for example M:\.
To build the CTSY, in -the command prompt window, change directory to M:\ \ctsy\group
This directory should -contain a file called “bld.inf”
Type

bldmake -bldfiles

If there are no errors, the command should give -no output and the user is returned to the command prompt.
Build the Mock SY, type

abld -test build winscw udeb

This builds the CTSY with and without -Dispatcher. The build tools are invoked and output scrolls up the screen. -There should be no build errors.

To build the CTSYDispatcher, in the -command prompt window, change directory to M:\ \ctsydispatcher\group\

and -repeat the above.
Testing the components
1. Return to the CTSY directory, -build the test components which consists of the LTSY Stub by typing
  
  abld -test build winscw udeb
  
  This command builds the test components -associated with the project for the WINSCW debug target. Output scrolls up -the screen and the user will be returned to the command prompt with no errors.
2. To build the CommonstkTSY, -in the command prompt window, change directory to M:\ \commonstkTSY\group -and repeat the above command
3. To build the CTSYDispatcher, -in the command prompt window, change directory to M:\ \ctsydispatcher\group\ -and repeat the above command
To confirm that the -production and test components have been built correctly, look inside the -directory containing the WINSCW debug binaries:
M:\epoc32\release\winscw\udeb
where M:\ is the drive containing the CBR environment), sort the files -by most recently modified date first and check that the following binaries -have been created
- customapi.dll – -CTSY Custom API (with or without Dispatcher)
- commontsy.dll – -common TSY without Dispatcher.
- commontsyfordispatcher.dll – -common TSY with Dispatcher
- phonetsy.tsy – -phone TSY without Dispatcher
- phonetsywithdispatcher.tsy – -phone TSY with Dispatcher
- licenseetsy.dll – -licensee TSY for testing common TSY without Dispatcher
- licenseeskeletontsy.dll – -licensee TSY for test common TSY with Dispatcher
Running the tests application
1. Edit the file M:\epoc32\data\epoc.ini -with a text editor and add the following line
  startupmode 1
2. Enable logging of the -CTSY and the LTSY Stub by copying the file
  commsdbg.ini to M:\epoc32\winscw\c\logs - -
3. run the test framework

-LTSY Interfaces -for CTSY with Dispatcher + + + + + +LTSY +for Dispatcher Tutorial This topic describes how to implement a Licensee TSY for the Common +TSY with the Dispatch layer. +

Developers implementing +the LTSY can start from the skeleton code at ../ctsydispatcher/ltsyskeleton_using_dispatcher/...

The +skeleton is a list of source files with empty implementations. The skeleton +is for guidance and the implementation depends on the requirements of the +handset manufacturer. The skeleton code contains mock test code for testing +purpose. The skeleton code can be conditionally recompiled to remove the calls +into the Mock test component, thus allowing the developer to run the existing +tests against the actual LTSY implementation they are creating with minimal +changes. Check the header file comments for mock test code. The request handlers +that must be implemented by the LTSY are declared in mltsydispatchcallcontrolinterface.h.

+ + +Start developing the LTSY from the skeleton code + + +Implement the different interfaces based on functional units. +The required interface implementations depend the baseband. + + +The interfaces are split into different functional units. Implement +a call-back function for every asynchronous dispatcher call. + + +If the methods used to receive the baseband notification use blocking +API calls, create a new thread to receive the notification information in +the LTSY. + + +Remove the Symbian test macros + + +The LTSY must map the baseband error codes to Symbian error codes defined +in the header files exterror.h and gsmerror.h. + + +LTSY example

A +sample LTSY implementation to dial a voice call is given below.

Implementing MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL() interface:

+virtual TInt HandleDialVoiceReqL(RMobilePhone::TMobilePhoneALSLine aCallLine, +RMobilePhone::TMobileAddress&amp, aDialledParty, +RMobileCall::TMobileCallParamsV1&amp, aCallParamsV1, TBool aIsIsvCall, +RMobileCall::TCallParamOrigin aCallOrigin) = 0; + +/** + * The CTSY Dispatcher shall invoke this function on receiving the EEtelCallDial + * request from the CTSY for dialling a voice call. + * + * It is a request call that is completed by invoking + * CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp + * + * Implementation of this interface should + * dial the requested voice call and complete the callback to indicate + * that an attempt to dial the call has been made. The callback function is used + * to indicate the outcome of this attempt to initiate the dialling process. + * + * @param aCallLine The line to use to dial the call. This parameter can have + * one of two possible values RMobilePhone::EAlternateLinePrimary to use the + * primary voice line or RMobilePhone::EAlternateLineAuxiliary to use the + * auxiliary voice line. + * + * @param aDialledParty Details about the dialled party including the phone + * number to dial. + * @param aCallParamsV1 The call parameters of the call to dial. If aIsIsvCall + * is set to ETrue, only the field RMobileCall::TMobileCallParamsV1::iIdRestrict + * and RMobileCall::TMobileCallParamsV1::iAutoRedial fields are valid. + * + * @param aIsIsvCall Indicates whether the call originated from a third party + * application which would have used the CTelephony class to dial the call. + * This information is provided in case the LTSY wishes to do special handling + * for third party calls, for example, not allow third party applications to + * place emergency calls. See also + * MLtsyDispatchCallControlQueryIsEmergencyNumber::HandleQueryIsEmergencyNumberSyncL + * See also: CTelephony::DialNewCall and RMobileCall::DialISV + * + * @param aCallOrigin The origin of the dial request. For example, whether the dial came from an Etel client or the SIM or another source. + * + * @return KErrNone on success; KErrNotSupported if the LTSY does not support handling of this request or another error code + *indicating the failure otherwise. + */ +

Call back function to complete the call dial request:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp( + TInt aError, TInt aCallId) + +/** + * Callback function to be used by the Licensee LTSY to complete a pending + * MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL + * + * When a dial attempt is made via the above mentioned interface, the LTSY has the + * responsibility of allocating a unique Call ID to the call. For more + * information, see the documentation on aCallId below. + * + * @param aError The error code to be returned to the CTSY Dispatcher by the LTSY + * indicating the outcome of the attempt to dial the requested call. This should + * be KErrNone if the dialling process could be started successfully. Otherwise + * another error code to indicate the failure should be returned. + * + * @param aCallId The call ID of the call that the dial attempt refers to which + * has been allocated by the LTSY. This should be a number between 1 and + * KMaxCallIdValue and should be unique across all call modes (voice, data etc.). + * For example, if a request for a voice call is made and the LTSY allocates + * this call an ID of 1 and a request for a data call is requested, the LTSY + * should allocate a Call ID which is not the same as that already allocated for + * the first voice call. + * + */ +

To indicate call status change notifications, use the following +callback:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlNotifyCallStatusChangeInd( + TInt aCauseCode, TInt aCallId, RMobileCall::TMobileCallStatus aMobileCallStatus) + +/** + * Used by an LTSY to indicate to the CTSY that there has been a change in the + * status of a call. For example, if the CTSY has previously made a dial request + * to make a voice call, the LTSY can call this API to notify the CTSY + * of progress of the call through the dialling, connecting and connected states. + * + * The aCauseCode parameter should be used to indicate the reason for the change + * in status of a call. + * + * In the case of a call going idle (aMobileCallStatus = RMobileCall::EStatusIdle) + * specific cause codes need to be returned to the Common TSY to indicate + * specific causes of status changes: + * + * To indicate that an active call has been released normally by either party, + * set aCauseCode = KErrGsmCCNormalCallClearing. + * + * To indicate that a mobile originated call that is being dialled has gone + * idle because the remote party has rejected the call, set + * aCauseCode = KErrGsmCCCallRejected or another error code (which is != KErrNone) + * to indicate the reason for rejection. + * + * If a mobile originated call is being dialled and the user cancels dialling, + * causing the call to go idle, set aCauseCode = KErrGsmCCNormalCallClearing. + * + * When an incoming call goes idle because the client has rejected it + * (done using RCall::HangUp on the ringing call), set + * aCauseCode = KErrGsmCCUserBusy. + * + * @param aCauseCode The cause of the change in call status. + * + * @param aCallId The Call ID of the call whose status has changed. + * + * @param aMobileCallStatus The new status of the call refered to by aCallId. + * + * @see RMobileCall::NotifyMobileCallStatusChange + */ + +

Implement other functions supported by the baseband and it +is the responsibility of the LTSY to return appropriate error code in the +call back function if it fails to establish a call.

Build and run the +components.

Unzip code to your target +disk for example M:\.
To build the CTSY, in +the command prompt window, change directory to M:\ \ctsy\group
This directory should +contain a file called “bld.inf”
Type

bldmake +bldfiles

If there are no errors, the command should give +no output and the user is returned to the command prompt.
Build the Mock SY, type

abld +test build winscw udeb

This builds the CTSY with and without +Dispatcher. The build tools are invoked and output scrolls up the screen. +There should be no build errors.

To build the CTSYDispatcher, in the +command prompt window, change directory to M:\ \ctsydispatcher\group\

and +repeat the above.
Testing the components
1. Return to the CTSY directory, +build the test components which consists of the LTSY Stub by typing
  
  abld +test build winscw udeb
  
  This command builds the test components +associated with the project for the WINSCW debug target. Output scrolls up +the screen and the user will be returned to the command prompt with no errors.
2. To build the CommonstkTSY, +in the command prompt window, change directory to M:\ \commonstkTSY\group +and repeat the above command
3. To build the CTSYDispatcher, +in the command prompt window, change directory to M:\ \ctsydispatcher\group\ +and repeat the above command
To confirm that the +production and test components have been built correctly, look inside the +directory containing the WINSCW debug binaries:
M:\epoc32\release\winscw\udeb
where M:\ is the drive containing the CBR environment), sort the files +by most recently modified date first and check that the following binaries +have been created
- customapi.dll – +CTSY Custom API (with or without Dispatcher)
- commontsy.dll – +common TSY without Dispatcher.
- commontsyfordispatcher.dll – +common TSY with Dispatcher
- phonetsy.tsy – +phone TSY without Dispatcher
- phonetsywithdispatcher.tsy – +phone TSY with Dispatcher
- licenseetsy.dll – +licensee TSY for testing common TSY without Dispatcher
- licenseeskeletontsy.dll – +licensee TSY for test common TSY with Dispatcher
Running the tests application
1. Edit the file M:\epoc32\data\epoc.ini +with a text editor and add the following line
  startupmode 1
2. Enable logging of the +CTSY and the LTSY Stub by copying the file
  commsdbg.ini to M:\epoc32\winscw\c\logs + +
3. run the test framework

+LTSY Interfaces +for CTSY with Dispatcher

\ No newline at end of file