Proactive -Command Tutorial

diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-05C443D3-C9E5-5A6D-828B-70A50CDB8962.dita --- a/Symbian3/PDK/Source/GUID-05C443D3-C9E5-5A6D-828B-70A50CDB8962.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-05C443D3-C9E5-5A6D-828B-70A50CDB8962.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,329 +1,329 @@ - - - - - -Proactive -Command TutorialThe proactive command tutorial describes how to use the different -proactive commands in Symbian OS. - - -

The proactive commands are inherited from TSatPCmdBase object. -A proactive command is executed when one the SAT engines have requested for -a notification. TSY responds with an error message in the terminal response, -without a SAT engine request. Developers can start with a reference TSY framework -which implements the Core telephony API or write a new TSY. Add the other -features like Multimode then create a SAT engine. The member functions of -the RSat API are used to implement the SAT engine.

- - -Create an instance of RPhone - - -Create an instance of RSat client - - -Get the features supported by the phone hardware and the TSY by calling GetMeSideSatProfile(). -The features are returned to the SAT engine as a profile. - - -Now modify the features supported by the new SAT engine by setting up -the flags in the profile and send the features to the ICC by calling ClientSatProfileIndication(). - - -Request some proactive command -notification messages. The phone polls the TSY for proactive commands. The -TSY notifies the SAT engine when a proactive command requested by the SAT -engine is received. -Some of proactive commands that you can request are: - - -Use NotifyDisplayTextPCmd() to send a request to display -text to the user. - -TSY completes the request when it receives a display text proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TDisplayTextV6 object and a terminal -response is sent to the ICC. - -Use NotifyGetInkeyPCmd() to get a single character input -from the user. - -The TSY completes the request when it receives a get inkey proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TGetInkeyV6 object and a terminal -response is sent to the ICC. - -Use NotifyGetInputPCmd() to get a string as an input from -the user. - -The TSY completes the request when it receives a get input proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TGetInputV6 object and a terminal -response is sent to the ICC. - -Use NotifyPlayTonePCmd to request the TSY to play a tone. - -The TSY completes the request when it receives the play tone proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TPlayToneV6 and a terminal response -is sent to the ICC. - -Use NotifySetUpMenuPCmd() to request the TSY to set up -a menu item. - -The TSY completes the request when it receives a proactive command from -the ICC. The common menu based commands are: -

set up menu
set up a menu item
add a menu item
select a menu item

- -The TSY completes these commands when there are some outstanding requests -from a SAT engine. - -Use NotifySelectItemPCmd() to request the TSY to send -a selected menu item to the ICC. - -When the TSY completes the request the selected menu item is sent to -the ICC in a terminal response. For more options in using the menu based proactive -commands, see RSat. - -Use NotifySendSmPCmd() to request the TSY to send an SMS. - -The TSY sends an SMS as soon as it receives a send SM proactive command -from the ICC. The proactive command information is sent to the SAT engine -in a TSendSmV6 object and a terminal response -is sent to the ICC. - -Use NotifySendSsPCmd() to request for a supplementary -service (SS). - -The TSY completes the request when it receives a send SS proactive command -from the ICC. The proactive command information is sent to the SAT engine -in a TSendSsV6 and a terminal response is -sent to the ICC. - -Use NotifySendussdPCmd() to request the TSY for an Unstructured -service data (USSD). - -The TSY completes the request when it receives a send USSD proactive -command from the ICC. The proactive command information is sent in a TSendUssdV6 object and a terminal response is sent -to the ICC. - -Use NotifySetUpCallPCmd() to request the TSY to set up -a call. - -The TSY completes the request when it receives a set up call proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TSetUpCallV6 object and a terminal -response is sent to the ICC. - -Use NotifyRefreshPCmd() to get the notification of any -changes in the ICC. - -The TSY first completes an outstanding NotifyRefreshRequired() command. -The TSY checks if a refresh is allowed by calling NotifyRefreshAllowed(). -The list of file identifiers are sent to the SAT engine using a TRefreshFileList and -the proactive command information is sent in a TRefreshV2 object. -A terminal response is sent to the ICC. - -Use NotifySetUpEventListPCmd() to request the TSY to notify -the ICC with the list of events occurring in the phone. - -The TSY completes the request when it receives a setup event list proactive -command. The proactive command information is sent in a TSetUpEventListV1 object -and a terminal response is sent to the ICC. - -Use NotifySetUpIdleModePCmd() to request the TSY to display -a text or an icon when the phone is idle. - -The TSY completes the request when it receives a setup idle mode text -proactive command from the ICC. The proactive command information is sent -to the SAT engine in a TSetUpIdleModeTextV6 object -and a terminal response is sent to the ICC. - -Use NotifySendDtmfPCmd() to request the TSY to send a -DTMF string. - -The TSY completes the request when it receives a send DTMF proactive -command from the ICC. The proactive command information is sent to the SAT -engine in a TSendDtmfV6 object and a terminal -response is sent to the ICC. - -Use NotifySendApduPCmd() to request the TSY to perform -a card APDU. - -The TSY completes the request when it receives a perform card APDU proactive -command from the ICC. The SAT engine must perform the a card APDU in the card -specified by the ICC. The APDU command and the destination ID of the specific -card is sent to the TSY in a TPerformCardApduV2 object -and a terminal response is sent to the ICC. - -Use NotifyPowerOffCardPCmd() to request the TSY to close -a specific session with a card. - -The TSY completes the request when it receives a power off proactive -command from the ICC. The SAT engine must close the session with a card specified -by the ICC. The destination ID of the specific card is sent in a TPowerOffCardV2 object and a terminal response is -sent to the ICC. - -Use NotifyPowerOnCardPCmd() to request the TSY to open -a session with a new card. - -The TSY completes the request when it receives a power on card proactive -command from the ICC. The SAT engine must open a session with the card specified -by the ICC. The destination ID of the specific card is sent in a TPowerOnCardV2 object and a terminal response is sent -to the ICC. If the card is already switched on then a reset is applied. It -is recommended to power the card only for the necessary duration for an efficient -use of the battery. - -Use NotifyGetReaderStatusPCmd() to request the TSY to -get the status of a card reader. - -The TSY completes the request when it receives a get card reader proactive -command from the ICC. The SAT engine scans all the cards, if the requested -mode is card reader status it sends the status using a TGetCardReaderStatusV2. -If the requested mode is card reader identifier then the identifier of the -card is returned by the SAT engine. When the request is complete a terminal -response is sent to the ICC. - -Use NotifyRunAtCommandPCmd() to request the TSY to run -an AT command. - -The TSY completes the request when it receives a run AT proactive command -from the ICC. The AT commands are specified in a TRunAtCommandV6 object. -SAT engine must pass the AT command to the phone. When completed the result -is returned in a terminal response. - -Use NotifyLanguageNotificationPCmd() to send the text -language issued by the ICC. - -The TSY completes the request when it receives a language notification -proactive command from the ICC. The proactive command information is sent -in a TLanguageNotificationV2 object. The -SAT engine must use the language specified by the ICC. A terminal response -is then sent to the ICC. - -Use NotifyLaunchBrowserPCmd() to request to launch a browser -and open a specific URL. - -The TSY completes the request when it receives a launch browser proactive -command from the ICC. The proactive command information is sent in a TLaunchBrowserV6 object. The SAT engine must execute -the command and try to connect to the specified URL. The SAT engine get the -confirmation from the user about the session. The user selects to use the -existing session or to terminate the browser. A terminal response is then -sent to the ICC. - -Use NotifyOpenChannelPCmd() to request the TSY to open -a specific channel. - -The TSY completes the request when it receives an open channel proactive -command from the ICC. The proactive command information is sent in a TOpenChannelBaseV2 object. The SAT engine can request -the TSY to open a specific type of channel such as GPRS. The SAT engine must -notify the user about the new channel with an alpha identifier or an icon. -A terminal response is sent to the ICC. -Use TOpenCsChannelV6 for packet switching -network, TOpenGprsChannelV6 for GPRS, and TOpenLocalLinksChannelV6 for Bluetooth or IRDA connections. - -Use NotifyCloseChannelPCmd() to request the TSY to close -a specific channel. - -The TSY completes the request when it receives a close channel proactive -command from the ICC. The proactive command information is sent in a TCloseChannelV6 object. The SAT engine must terminate -the channel and notify the user. A terminal response is then sent to the ICC. - -Use NotifyReceiveDataPCmd() to request the TSY to get -the data from a channel. - -The TSY completes the request when it receives a receive data proactive -command from the ICC. The proactive command information is sent in a TReceivedataV6 object. The SAT engine must read the -data from the buffer and send it to the ICC. If sufficient amount of data -is not received, the ICC requests for more data from the SAT engine. The SAT -engine must notify the user about the data received with an alpha identifier -or an icon. A terminal response is then sent to the ICC. - -Use NotifySendDataPCmd() to request the TSY to send data -in an open channel. - -The TSY completes the request when it receives a send data proactive -command from the ICC. The proactive command information is sent in a TSendDataV6 object. The SAT engine must read the data -from the ICC and store it in the transmission (Tx) buffer or send the data -immediately when ICC issues a Send Immediate in the send -data command. A terminal response is then sent to the ICC. - -Use NotifyGetChannelStatusPCmd() to request the TSY to -get the status of an open channel. - -The TSY completes the request when it receives a get channel status -proactive command from the ICC. The proactive command information is sent -in a TGetChannelStatusV2 object and a terminal -response is then sent to the ICC. - -Use NotifyServiceSearchPCmd() to request the TSY to search -for a service. - -The TSY completes the request when it receives a search service proactive -command from the ICC. The proactive commands information is sent in a TSearchServiceV6 object and a terminal response is -sent to the ICC. - -Use NotifyGetServiceInfoPCmd() to request the TSY to get -information about a service. - -The TSY completes the request when it receives a get service info proactive -command from the ICC. The proactive command information is sent in a TGetServiceInfoV6 object and a terminal response is -sent to the ICC. - -Use NotifyDeclareServicePCmd() to request the TSY to declare -a service. - -The TSY completes the request when it receives a declare service proactive -command from the ICC. The proactive command information is sent in a TDeclareServiceV2 object and a terminal response is -sent to the ICC. - -Use NotifyTimerMgmtPCmd() to request the TSY to start, -stop or get the values of timers. - -The TSY completes the request when it receives a timer management proactive -command from the ICC. The proactive command information is sent in a TTimerMgmtV3 object and a terminal response is sent -to the ICC. - -Use NotifyLocalInfoPCmd() to request the TSY to send the -local information to the ICC. - -The TSY completes the request when it receives a provide local information -proactive command from the ICC. The proactive command information is sent -in a TLocalInfoV6 object and a terminal response -is sent to the ICC. - -Use NotifyPollingIntervalPCmd() to instruct the phone -about the polling frequency required by the ICC. - -The TSY completes the request when it receives a polling interval proactive -command from the ICC. The proactive command information is sent in a TPollingIntervalV3 object and a terminal response -is sent to the ICC. - -Use NotifyPollingOffPCmd to instruct the phone to stop -polling the ICC. - -The TSY completes the request when it receives a polling off proactive -command from the ICC. The proactive command information is sent in a TPollingOffV3 object and a terminal response is sent -to the ICC. - - - - -A feedback to each proactive command is sent to the TSY using a terminal -response. The TSY analyses the result and the additional information present -in the response and then sends a terminal response to the ICC. - - + + + + + +Proactive +Command TutorialThe proactive command tutorial describes how to use the different +proactive commands in Symbian platform. + + +

The proactive commands are inherited from TSatPCmdBase object. +A proactive command is executed when one the SAT engines have requested for +a notification. TSY responds with an error message in the terminal response, +without a SAT engine request. Developers can start with a reference TSY framework +which implements the Core telephony API or write a new TSY. Add the other +features like Multimode then create a SAT engine. The member functions of +the RSat API are used to implement the SAT engine.

+ + +Create an instance of RPhone + + +Create an instance of RSat client + + +Get the features supported by the phone hardware and the TSY by calling GetMeSideSatProfile(). +The features are returned to the SAT engine as a profile. + + +Now modify the features supported by the new SAT engine by setting up +the flags in the profile and send the features to the ICC by calling ClientSatProfileIndication(). + + +Request some proactive command +notification messages. The phone polls the TSY for proactive commands. The +TSY notifies the SAT engine when a proactive command requested by the SAT +engine is received. +Some of proactive commands that you can request are: + + +Use NotifyDisplayTextPCmd() to send a request to display +text to the user. + +TSY completes the request when it receives a display text proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TDisplayTextV6 object and a terminal +response is sent to the ICC. + +Use NotifyGetInkeyPCmd() to get a single character input +from the user. + +The TSY completes the request when it receives a get inkey proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TGetInkeyV6 object and a terminal +response is sent to the ICC. + +Use NotifyGetInputPCmd() to get a string as an input from +the user. + +The TSY completes the request when it receives a get input proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TGetInputV6 object and a terminal +response is sent to the ICC. + +Use NotifyPlayTonePCmd to request the TSY to play a tone. + +The TSY completes the request when it receives the play tone proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TPlayToneV6 and a terminal response +is sent to the ICC. + +Use NotifySetUpMenuPCmd() to request the TSY to set up +a menu item. + +The TSY completes the request when it receives a proactive command from +the ICC. The common menu based commands are: +

set up menu
set up a menu item
add a menu item
select a menu item

+ +The TSY completes these commands when there are some outstanding requests +from a SAT engine. + +Use NotifySelectItemPCmd() to request the TSY to send +a selected menu item to the ICC. + +When the TSY completes the request the selected menu item is sent to +the ICC in a terminal response. For more options in using the menu based proactive +commands, see RSat. + +Use NotifySendSmPCmd() to request the TSY to send an SMS. + +The TSY sends an SMS as soon as it receives a send SM proactive command +from the ICC. The proactive command information is sent to the SAT engine +in a TSendSmV6 object and a terminal response +is sent to the ICC. + +Use NotifySendSsPCmd() to request for a supplementary +service (SS). + +The TSY completes the request when it receives a send SS proactive command +from the ICC. The proactive command information is sent to the SAT engine +in a TSendSsV6 and a terminal response is +sent to the ICC. + +Use NotifySendussdPCmd() to request the TSY for an Unstructured +service data (USSD). + +The TSY completes the request when it receives a send USSD proactive +command from the ICC. The proactive command information is sent in a TSendUssdV6 object and a terminal response is sent +to the ICC. + +Use NotifySetUpCallPCmd() to request the TSY to set up +a call. + +The TSY completes the request when it receives a set up call proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TSetUpCallV6 object and a terminal +response is sent to the ICC. + +Use NotifyRefreshPCmd() to get the notification of any +changes in the ICC. + +The TSY first completes an outstanding NotifyRefreshRequired() command. +The TSY checks if a refresh is allowed by calling NotifyRefreshAllowed(). +The list of file identifiers are sent to the SAT engine using a TRefreshFileList and +the proactive command information is sent in a TRefreshV2 object. +A terminal response is sent to the ICC. + +Use NotifySetUpEventListPCmd() to request the TSY to notify +the ICC with the list of events occurring in the phone. + +The TSY completes the request when it receives a setup event list proactive +command. The proactive command information is sent in a TSetUpEventListV1 object +and a terminal response is sent to the ICC. + +Use NotifySetUpIdleModePCmd() to request the TSY to display +a text or an icon when the phone is idle. + +The TSY completes the request when it receives a setup idle mode text +proactive command from the ICC. The proactive command information is sent +to the SAT engine in a TSetUpIdleModeTextV6 object +and a terminal response is sent to the ICC. + +Use NotifySendDtmfPCmd() to request the TSY to send a +DTMF string. + +The TSY completes the request when it receives a send DTMF proactive +command from the ICC. The proactive command information is sent to the SAT +engine in a TSendDtmfV6 object and a terminal +response is sent to the ICC. + +Use NotifySendApduPCmd() to request the TSY to perform +a card APDU. + +The TSY completes the request when it receives a perform card APDU proactive +command from the ICC. The SAT engine must perform the a card APDU in the card +specified by the ICC. The APDU command and the destination ID of the specific +card is sent to the TSY in a TPerformCardApduV2 object +and a terminal response is sent to the ICC. + +Use NotifyPowerOffCardPCmd() to request the TSY to close +a specific session with a card. + +The TSY completes the request when it receives a power off proactive +command from the ICC. The SAT engine must close the session with a card specified +by the ICC. The destination ID of the specific card is sent in a TPowerOffCardV2 object and a terminal response is +sent to the ICC. + +Use NotifyPowerOnCardPCmd() to request the TSY to open +a session with a new card. + +The TSY completes the request when it receives a power on card proactive +command from the ICC. The SAT engine must open a session with the card specified +by the ICC. The destination ID of the specific card is sent in a TPowerOnCardV2 object and a terminal response is sent +to the ICC. If the card is already switched on then a reset is applied. It +is recommended to power the card only for the necessary duration for an efficient +use of the battery. + +Use NotifyGetReaderStatusPCmd() to request the TSY to +get the status of a card reader. + +The TSY completes the request when it receives a get card reader proactive +command from the ICC. The SAT engine scans all the cards, if the requested +mode is card reader status it sends the status using a TGetCardReaderStatusV2. +If the requested mode is card reader identifier then the identifier of the +card is returned by the SAT engine. When the request is complete a terminal +response is sent to the ICC. + +Use NotifyRunAtCommandPCmd() to request the TSY to run +an AT command. + +The TSY completes the request when it receives a run AT proactive command +from the ICC. The AT commands are specified in a TRunAtCommandV6 object. +SAT engine must pass the AT command to the phone. When completed the result +is returned in a terminal response. + +Use NotifyLanguageNotificationPCmd() to send the text +language issued by the ICC. + +The TSY completes the request when it receives a language notification +proactive command from the ICC. The proactive command information is sent +in a TLanguageNotificationV2 object. The +SAT engine must use the language specified by the ICC. A terminal response +is then sent to the ICC. + +Use NotifyLaunchBrowserPCmd() to request to launch a browser +and open a specific URL. + +The TSY completes the request when it receives a launch browser proactive +command from the ICC. The proactive command information is sent in a TLaunchBrowserV6 object. The SAT engine must execute +the command and try to connect to the specified URL. The SAT engine get the +confirmation from the user about the session. The user selects to use the +existing session or to terminate the browser. A terminal response is then +sent to the ICC. + +Use NotifyOpenChannelPCmd() to request the TSY to open +a specific channel. + +The TSY completes the request when it receives an open channel proactive +command from the ICC. The proactive command information is sent in a TOpenChannelBaseV2 object. The SAT engine can request +the TSY to open a specific type of channel such as GPRS. The SAT engine must +notify the user about the new channel with an alpha identifier or an icon. +A terminal response is sent to the ICC. +Use TOpenCsChannelV6 for packet switching +network, TOpenGprsChannelV6 for GPRS, and TOpenLocalLinksChannelV6 for Bluetooth or IRDA connections. + +Use NotifyCloseChannelPCmd() to request the TSY to close +a specific channel. + +The TSY completes the request when it receives a close channel proactive +command from the ICC. The proactive command information is sent in a TCloseChannelV6 object. The SAT engine must terminate +the channel and notify the user. A terminal response is then sent to the ICC. + +Use NotifyReceiveDataPCmd() to request the TSY to get +the data from a channel. + +The TSY completes the request when it receives a receive data proactive +command from the ICC. The proactive command information is sent in a TReceivedataV6 object. The SAT engine must read the +data from the buffer and send it to the ICC. If sufficient amount of data +is not received, the ICC requests for more data from the SAT engine. The SAT +engine must notify the user about the data received with an alpha identifier +or an icon. A terminal response is then sent to the ICC. + +Use NotifySendDataPCmd() to request the TSY to send data +in an open channel. + +The TSY completes the request when it receives a send data proactive +command from the ICC. The proactive command information is sent in a TSendDataV6 object. The SAT engine must read the data +from the ICC and store it in the transmission (Tx) buffer or send the data +immediately when ICC issues a Send Immediate in the send +data command. A terminal response is then sent to the ICC. + +Use NotifyGetChannelStatusPCmd() to request the TSY to +get the status of an open channel. + +The TSY completes the request when it receives a get channel status +proactive command from the ICC. The proactive command information is sent +in a TGetChannelStatusV2 object and a terminal +response is then sent to the ICC. + +Use NotifyServiceSearchPCmd() to request the TSY to search +for a service. + +The TSY completes the request when it receives a search service proactive +command from the ICC. The proactive commands information is sent in a TSearchServiceV6 object and a terminal response is +sent to the ICC. + +Use NotifyGetServiceInfoPCmd() to request the TSY to get +information about a service. + +The TSY completes the request when it receives a get service info proactive +command from the ICC. The proactive command information is sent in a TGetServiceInfoV6 object and a terminal response is +sent to the ICC. + +Use NotifyDeclareServicePCmd() to request the TSY to declare +a service. + +The TSY completes the request when it receives a declare service proactive +command from the ICC. The proactive command information is sent in a TDeclareServiceV2 object and a terminal response is +sent to the ICC. + +Use NotifyTimerMgmtPCmd() to request the TSY to start, +stop or get the values of timers. + +The TSY completes the request when it receives a timer management proactive +command from the ICC. The proactive command information is sent in a TTimerMgmtV3 object and a terminal response is sent +to the ICC. + +Use NotifyLocalInfoPCmd() to request the TSY to send the +local information to the ICC. + +The TSY completes the request when it receives a provide local information +proactive command from the ICC. The proactive command information is sent +in a TLocalInfoV6 object and a terminal response +is sent to the ICC. + +Use NotifyPollingIntervalPCmd() to instruct the phone +about the polling frequency required by the ICC. + +The TSY completes the request when it receives a polling interval proactive +command from the ICC. The proactive command information is sent in a TPollingIntervalV3 object and a terminal response +is sent to the ICC. + +Use NotifyPollingOffPCmd to instruct the phone to stop +polling the ICC. + +The TSY completes the request when it receives a polling off proactive +command from the ICC. The proactive command information is sent in a TPollingOffV3 object and a terminal response is sent +to the ICC. + + + + +A feedback to each proactive command is sent to the TSY using a terminal +response. The TSY analyses the result and the additional information present +in the response and then sends a terminal response to the ICC. + + \ No newline at end of file