1 /* Copyright (c) 2013, 2015 The Linux Foundation. All rights reserved. 2 * 3 * Redistribution and use in source and binary forms, with or without 4 * modification, are permitted provided that the following conditions are 5 * met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above 9 * copyright notice, this list of conditions and the following 10 * disclaimer in the documentation and/or other materials provided 11 * with the distribution. 12 * * Neither the name of The Linux Foundation, nor the names of its 13 * contributors may be used to endorse or promote products derived 14 * from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 20 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 26 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 #ifndef _DS_CLIENT_H_ 30 #define _DS_CLIENT_H_ 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @file 38 * @brief DS client API declaration. 39 * 40 * @ingroup loc_ds_api 41 */ 42 43 /** 44 * @addtogroup loc_ds_api DS client support for location 45 * @{ 46 */ 47 48 /** 49 * @brief Function name for DS client interface query. 50 * 51 * @sa ds_client_get_interface 52 */ 53 #define DS_CLIENT_GET_INTERFACE_FN "ds_client_get_interface" 54 /** 55 * @brief Library name for loading DS client 56 */ 57 #define DS_CLIENT_LIB_NAME "libloc_ds_api.so" 58 59 typedef void* dsClientHandleType; 60 61 typedef enum 62 { 63 E_DS_CLIENT_SUCCESS = 0, 64 /**< Request was successful. */ 65 66 E_DS_CLIENT_FAILURE_GENERAL = 1, 67 /**< Failed because of a general failure. */ 68 69 E_DS_CLIENT_FAILURE_UNSUPPORTED = 2, 70 /**< Failed because the service does not support the command. */ 71 72 E_DS_CLIENT_FAILURE_INVALID_PARAMETER = 3, 73 /**< Failed because the request contained invalid parameters. */ 74 75 E_DS_CLIENT_FAILURE_ENGINE_BUSY = 4, 76 /**< Failed because the engine is busy. */ 77 78 E_DS_CLIENT_FAILURE_PHONE_OFFLINE = 5, 79 /**< Failed because the phone is offline. */ 80 81 E_DS_CLIENT_FAILURE_TIMEOUT = 6, 82 /**< Failed because of a timeout. */ 83 84 E_DS_CLIENT_FAILURE_SERVICE_NOT_PRESENT = 7, 85 /**< Failed because the service is not present. */ 86 87 E_DS_CLIENT_FAILURE_SERVICE_VERSION_UNSUPPORTED = 8, 88 /**< Failed because the service version is unsupported. */ 89 90 E_DS_CLIENT_FAILURE_CLIENT_VERSION_UNSUPPORTED = 9, 91 /**< Failed because the service does not support client version. */ 92 93 E_DS_CLIENT_FAILURE_INVALID_HANDLE = 10, 94 /**< Failed because an invalid handle was specified. */ 95 96 E_DS_CLIENT_FAILURE_INTERNAL = 11, 97 /**< Failed because of an internal error in the service. */ 98 99 E_DS_CLIENT_FAILURE_NOT_INITIALIZED = 12, 100 /**< Failed because the service has not been initialized. */ 101 102 E_DS_CLIENT_FAILURE_NOT_ENOUGH_MEMORY = 13, 103 /**< Failed because not rnough memory to do the operation.*/ 104 105 E_DS_CLIENT_SERVICE_ALREADY_STARTED = 14, 106 /*Service is already started*/ 107 108 E_DS_CLIENT_DATA_CALL_CONNECTED = 15, 109 110 E_DS_CLIENT_DATA_CALL_DISCONNECTED = 16, 111 112 E_DS_CLIENT_RETRY_LATER = 17 113 } ds_client_status_enum_type; 114 115 /** 116 * @brief Callback function interface for handling DS service indications 117 * 118 * @param[in] result Operation result (error code). 119 * @param[in] cookie Client cookie provided when call is opened. 120 * 121 * @sa ds_client_cb_data 122 */ 123 typedef void ds_client_event_ind_cb_type 124 ( 125 ds_client_status_enum_type result, 126 void* loc_adapter_cookie 127 ); 128 129 /** 130 * @brief Client callback function table 131 * 132 * This structure contains callback functions provided by client of DS client 133 * API for delivering event notifications. 134 * 135 * @sa ds_client_open_call_type 136 */ 137 typedef struct { 138 ds_client_event_ind_cb_type *event_cb; 139 } ds_client_cb_data; 140 141 /** 142 * @brief Initialize the DS client service 143 * 144 * This function is to be called as a first step by each process that 145 * needs to use data services. This call internally calls dsi_init() 146 * and prepares the module for making data calls. 147 * Needs to be called once for every process 148 * 149 * @return Operation result 150 * @retval E_DS_CLIENT_SUCCESS On success. 151 * @retval E_DS_CLIENT_FAILURE... On error. 152 */ 153 typedef ds_client_status_enum_type ds_client_init_type(); 154 155 /** 156 * @brief Prepares for call. 157 * 158 * Obtains a handle to the dsi_netctrl layer and looks up the profile 159 * to make the call. As of now. It only searches for profiles that 160 * support emergency calls. 161 * 162 * Function to open an emergency call. Does the following things: 163 * - Obtains a handle to the WDS service 164 * - Obtains a list of profiles configured in the modem 165 * - Queries each profile and obtains settings to check if emergency calls 166 * are supported 167 * - Returns the profile index that supports emergency calls 168 * - Returns handle to dsi_netctrl 169 * 170 * @param[out] client_handle Client handle to initialize. 171 * @param[in] callback Pointer to callback function table. 172 * @param[in] cookie Client's cookie for using with callback calls. 173 * @param[out] profile_index Pointer to profile index number. 174 * @param[out] pdp_type Pointer to PDP type. 175 * 176 * @return Operation result 177 * @retval E_DS_CLIENT_SUCCESS On success. Output parameters are initialized. 178 * @retval E_DS_CLIENT_FAILURE... On error. 179 */ 180 typedef ds_client_status_enum_type ds_client_open_call_type 181 ( 182 dsClientHandleType *client_handle, 183 const ds_client_cb_data *callback, 184 void *cookie, 185 int *profile_index, 186 int *pdp_type 187 ); 188 189 /** 190 * @brief Starts a data call using the profile number provided 191 * 192 * The function uses parameters provided from @a ds_client_open_call_type 193 * call result. 194 * 195 * @param[in] client_handle Client handle 196 * @param[in] profile_index Profile index 197 * @param[in] pdp_type PDP type 198 * 199 * @return Operation result 200 * @retval E_DS_CLIENT_SUCCESS On success. 201 * @retval E_DS_CLIENT_FAILURE... On error. 202 */ 203 typedef ds_client_status_enum_type ds_client_start_call_type 204 ( 205 dsClientHandleType client_handle, 206 int profile_index, 207 int pdp_type 208 ); 209 210 /** 211 * @brief Stops a data call associated with the handle 212 * 213 * @param[in] client_handle Client handle 214 * 215 * @return Operation result 216 * @retval E_DS_CLIENT_SUCCESS On success. 217 * @retval E_DS_CLIENT_FAILURE... On error. 218 */ 219 typedef ds_client_status_enum_type ds_client_stop_call_type 220 ( 221 dsClientHandleType client_handle 222 ); 223 224 /** 225 * @brief Releases the handle used for making data calls 226 * 227 * @param[in,out] client_handle Client handle pointer 228 * 229 * @return None 230 */ 231 typedef void ds_client_close_call_type 232 ( 233 dsClientHandleType *client_handle 234 ); 235 236 /** 237 * @brief DS client functional interface table 238 * 239 * This table contains all supported DS client operations. If the operation 240 * is not supported, the corresponding entry is NULL. 241 * 242 * @sa ds_client_get_interface 243 */ 244 typedef struct 245 { 246 ds_client_init_type *pfn_init; 247 ds_client_open_call_type *pfn_open_call; 248 ds_client_start_call_type *pfn_start_call; 249 ds_client_stop_call_type *pfn_stop_call; 250 ds_client_close_call_type *pfn_close_call; 251 } ds_client_iface_type; 252 253 /** 254 * @brief Function for accessing DS client functional interface 255 * 256 * @return Pointer to interface structure. 257 */ 258 typedef const ds_client_iface_type *ds_client_get_iface_fn(); 259 260 /** 261 * @brief Function for accessing DS client functional interface 262 * 263 * @return Pointer to interface structure. 264 */ 265 ds_client_get_iface_fn ds_client_get_interface; 266 267 #ifdef __cplusplus 268 } 269 #endif 270 271 /** 272 * @} 273 */ 274 275 #endif /* _DS_CLIENT_H_ */ 276