Proactive Command Tutorial

The proactive command tutorial describes how to use the different proactive commands in Symbian platform.

1. 
   Create an instance of RPhone
2. 
   Create an instance of RSat client
3. 
   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.
4. 
   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().
5. 
   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:
   1. 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.
   2. 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.
   3. 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.
   4. 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.
   5. 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.
   6. 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.
   7. 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.
   8. 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.
   9. 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.
   10. 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.
   11. 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.
   12. 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.
   13. 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.
   14. 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.
   15. 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.
   16. 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.
   17. 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.
   18. 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.
   19. 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.
   20. 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.
   21. 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.
   22. 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.
   23. 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.
   24. 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.
   25. 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.
   26. 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.
   27. 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.
   28. 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.
   29. 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.
   30. 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.
   31. 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.
   32. 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.
   33. 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.
6. 
   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.