4 * Copyright (c) 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Ja-young Gu <jygu@samsung.com>
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
23 * @ingroup TelephonyAPI
24 * @addtogroup SAT_TAPI SAT
29 @brief This file serves as a "C" header file defines functions for Tapi Sat Services.\n
30 It contains a sample set of function prototypes that would be required by applications.
32 Note: Telephony SAT functionality is message relaying from USIM application to SAT related applications.
38 #include <tapi_common.h>
40 #include <TelDefines.h>
48 * @brief Sends the user choice of the main menu options to the USIM.
51 * A set of possible menu options is supplied by the USIM
52 * using the proactive command SET UP MENU. Telephony server receives the command
53 * and publishes this information.SAT UI application should list the menu when it initially launched.
54 * If the user subsequently chooses an option, then SAT UI application replies
55 * the command with user's choice using this API.
57 * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
58 * However it just means that the API request has been transfered to the CP successfully.
59 * The actual operation result is delivered with the async response as below.
62 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
64 * @par Sync (or) Async:
65 * This is an Asynchronous API.
68 * - handle from tel_init().
70 * @param [in] pMenuSelect
71 * - #TelSatMenuSelectionReqInfo_t contains information like which SAT menu item has been selected or whether Help is required.
73 * @param [in] callback
74 * - To register callback function for result.
76 * @param [in] user_data
77 * - user_data for user specification.
79 * @par Async Response Message:
80 * - The event associated is TAPI_EVENT_SAT_MENU_SELECTION_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp_t.
83 * - This function supposed to be called after getting TAPI_EVENT_SAT_SETUP_MENU_IND event from telephony server\n
88 * @return Return Type (int) \n
89 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
90 * - Else it will return failure and error code (Refer #TapiResult_t)
92 * @par Prospective Clients:
95 * @see tel_get_sat_main_menu_info
98 * #include <ITapiSat.h>
100 * TapiHandle *handle; // Handle given by tel_init()
101 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
102 * TelSatMenuSelectionReqInfo_t selected_menu;
103 * void *user_data; // Set User data
104 * selected_menu.itemIdentifier = '1'; //selected menu num
105 * selected_menu.bIsHelpRequested = 0;
106 * ret_status = tel_select_sat_menu(handle, &selected_menu, callback, user_data);
113 /*================================================================================================*/
114 int tel_select_sat_menu(TapiHandle *handle, const TelSatMenuSelectionReqInfo_t* pMenuSelect, tapi_response_cb callback, void *user_data);
117 * @brief Download SAT events to USIM
120 * A set of events for the terminal to monitor can be supplied by the USIM using the proactive command SET UP EVENT
121 * LIST. If the USIM has sent this command, and an event which is part of the list subsequently occurs, the terminal
122 * informs the USIM using this function, relevant for that event.
123 * If USIM commands to monitor a browser termination event, the SAT-UI application has to call this function.
125 * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
126 * However it just means that the API request has been transfered to the CP successfully.
127 * The actual operation result is delivered with the async response as below.
130 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
132 * @par Sync (or) Async:
133 * This is an Asynchronous API.
136 * - handle from tel_init().
138 * @param [in] pEventData
139 * - #TelSatEventDownloadReqInfo_t contains the necessary parameters like event type and information associated with it.
141 * @param [in] callback
142 * - To register callback function for result.
144 * @param [in] user_data
145 * - user_data for user specification.
147 * @par Async Response Message:
148 * - The event associated is TAPI_EVENT_SAT_EVENT_DOWNLOAD_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp_t.
151 * - A SET UP EVENT LIST proactive command supplies a set of event to monitor.
156 * @return Return Type (int) \n
157 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
158 * - Else it will return failure and error code (Refer #TapiResult_t)
160 * @par Prospective Clients:
166 * #include <ITapiSat.h>
168 * TapiHandle *handle; // Handle given by tel_init()
169 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
170 * TelSatEventDownloadReqInfo_t pEventData;
171 * void *user_data; // Set User data
172 * pEventData.eventDownloadType = TAPI_EVENT_SAT_DW_TYPE_IDLE_SCREEN_AVAILABLE;
173 * pEventData.u.bIdleScreenAvailable = 1; //event occur or not
174 * ret_status = tel_download_sat_event(handle, &pEventData, callback, user_data);
181 /*================================================================================================*/
182 int tel_download_sat_event(TapiHandle *handle, const TelSatEventDownloadReqInfo_t* pEventData, tapi_response_cb callback, void *user_data);
185 * @brief Send the UI display status of the alpha identifier of a specific proactive command to Telephony Server.
187 * When SAT-UI receives a proactive command, SAT-UI should draw a UI for relevant command.
188 * As it completes , SAT-UI inform USIM with this function. Afterwards, USIM is getting ready to send another commands.
190 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
193 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
195 * @par Sync (or) Async:
196 * This is a Synchronous API.
199 * - handle from tel_init().
201 * @param [in] commandId
202 * - Specific proactive command id from the Application
205 * - #TelSatUiDisplayStatusType_t contain display status(SUCCESS/FAIL).
207 * @par Async Response Message:
211 * - Display request for the alpha identifier of a Proactive Command should be sent by Telephony Server.
214 * - If the display status is SUCCESS Telephony Server sends a request to application for Proactive Command Execution.
215 * - If the display status is FAIL Telephony Server sends Terminal Response for the Proactive Command.
217 * @return Return Type (int) \n
218 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
219 * - Else it will return failure and error code (Refer #TapiResult_t)
221 * @par Prospective Clients:
227 * #include <ITapiSat.h>
228 * int commandId = 1; //this value should be server given value
229 * TapiHandle *handle; // Handle given by tel_init()
231 * ret_status = tel_send_sat_ui_display_status(handle, commandId, TAPI_SAT_DISPLAY_SUCCESS);
238 /*================================================================================================*/
239 int tel_send_sat_ui_display_status(TapiHandle *handle, int commandId, TelSatUiDisplayStatusType_t status);
242 * @brief This function sends the UI User confirmation data for a specific Proactive Command to the Telephony Server.
244 * In case that the proactive commands need user response, SAT-UI can send it using this function.
245 * The response can be 'OK', 'Cancel', 'Move Back' and 'End Session'. Upon this response, USIM can send
246 * a proactive command subsequently to indicate next UI action.
248 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
251 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
253 * @par Sync (or) Async:
254 * This is a synchronous API.
257 * - handle from tel_init().
259 *@param [in] pUserConfirmData
260 * -#TelSatUiUserConfirmInfo_t contains Specific user confirmation data.
262 * @par Async Response Message:
266 * - User Confirmation request for a specific Proactive Command should be sent to application by Telephony Server.
269 * - If the User Confirmation is positive Telephony Server sends a request to application for Proactive Command Execution.
270 * - If the User Confirmation is negative Telephony Server sends Terminal Response for the Proactive Command.
272 * @return Return Type (int) \n
273 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
274 * - Else it will return failure and error code (Refer #TapiResult_t)
276 * @par Prospective Clients:
282 * #include <ITapiSat.h>
284 * TelSatUiUserConfirmInfo_t cfm_data;
285 * TapiHandle *handle; // Handle given by tel_init()
286 * cfm_data.commandId = '1'; //this value should be server given value
287 * cfm_data.commandType = TAPI_SAT_CMD_TYPE_SETUP_CALL;
288 * cfm_data.keyType = TAPI_SAT_USER_CONFIRM_YES;
289 * ret_status = tel_send_sat_ui_user_confirm(handle, &cfm_data);
296 /*================================================================================================*/
297 int tel_send_sat_ui_user_confirm(TapiHandle *handle, TelSatUiUserConfirmInfo_t *pUserConfirmData);
300 * @brief This function provides SAT(Sim Application toolkit) Main Menu information for SAT-UI.
302 * Once the USIM supplies the SET UP MENU proactive command, telephony server not only publish
303 * TAPI_EVENT_SAT_SETUP_MENU_IND event but also caches the menu information.
304 * The SAT-UI applicatoin can get the menu list using this function.
306 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
309 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
311 * @par Sync (or) Async:
312 * This is a Synchronous API.
315 * - handle from tel_init().
317 * @param [out] pMainMenu
318 * - #TelSatSetupMenuInfo_t contain all menu related information which are required like menu title, icon, item count, etc.
320 * @par Async Response Message:
324 * - When SAT SIM is inserted. we can get meaningful data. without SAT SIM, Null is returned
329 * @return Return Type (int) \n
330 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
331 * - Else it will return failure and error code (Refer #TapiResult_t)
333 * @par Prospective Clients:
336 * @see tel_select_sat_menu
339 * #include <ITapiSat.h>
341 * TapiHandle *handle; // Handle given by tel_init()
342 * TelSatSetupMenuInfo_t menu; //this struct will be pull up with SIM menu info
343 * ret_status = tel_get_sat_main_menu_info(handle, &menu);
350 /*================================================================================================*/
351 int tel_get_sat_main_menu_info(TapiHandle *handle, TelSatSetupMenuInfo_t *pMainMenu);
354 * @brief This API provides the Operation result(s) for the Proactive Command execution by the Application(s) to the Telephony Server.
356 * The USIM commands the terminal to do some predefined action, such as sending short message,
357 * making a voice call, launching an Internet browser and so on. Those actions are defined by 3GPP TS31.111.
358 * Once a application executes the requested action by USIM, it reports the operation result to USIM using this function.
360 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
363 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
365 * @par Sync (or) Async:
366 * This is a Synchronous API.
369 * - handle from tel_init().
371 * @param [out] pAppRetInfo
372 * - #TelSatAppsRetInfo_t contains execution result of a specific proactive command by application.
374 * @par Async Response Message:
378 * - Proactive Command execution request should be sent by Telephony Server to SAT related applications.
383 * @return Return Type (int) \n
384 * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
385 * - Else it will return failure and error code (Refer #TapiResult_t)
387 * @par Prospective Clients:
388 * Embeded applications which are predefined by 3GPP TS31.111
393 * #include <ITapiSat.h>
395 * TapiHandle *handle; // Handle given by tel_init()
396 * TelSatAppsRetInfo_t app_ret;
397 * app_ret.commandType = TAPI_SAT_CMD_TYPE_SETUP_CALL;
398 * app_ret.commandId = 1; //this value should be server given value
399 * app_ret.appsRet.setupCall.resp = TAPI_SAT_R_SUCCESS;
400 * ret_status = tel_send_sat_app_exec_result(handle, &app_ret);
407 /*================================================================================================*/
408 int tel_send_sat_app_exec_result(TapiHandle *handle, TelSatAppsRetInfo_t *pAppRetInfo);
415 #endif /* _ITAPI_SAT_H_ */