include/TapiUtility.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2014 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Ja-young Gu <jygu@samsung.com>
   7  *
   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
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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.
  19  */
  20
  21 /**
  22  * @file TapiUtility.h
  23  */
  24
  25 /**
  26  * @internal
  27  * @addtogroup CAPI_TELEPHONY_SERVICE
  28  * @{
  29  */
  30
  31 #ifndef _TEL_UTILITY_H_
  32 #define _TEL_UTILITY_H_
  33
  34 __BEGIN_DECLS
  35
  36 /**
  37  * @brief Definition for Invalid Request ID value.
  38  */
  39 #define INVALID_REQUEST_ID      -1
  40 #define DBUS_DEFAULT_PATH       "/org/tizen/telephony"
  41
  42 /**
  43  * @brief Definition for negative error value
  44  * @remarks If result is negative value in callback function, it comply below error.
  45  */
  46 #define TAPI_ERROR_OPERATION_FAILED -1
  47 #define TAPI_ERROR_ACCESS_DENIED -2
  48 #define TAPI_ERROR_OPERATION_NOT_SUPPORTED -3
  49
  50 /**
  51  * @brief Enumeration for TAPI return codes.
  52  */
  53 typedef enum {
  54         TAPI_API_SUCCESS = 0, /**< No Error occurred */
  55         TAPI_API_INVALID_INPUT = -1, /**< Input values are not correct in the TAPI Library */
  56         TAPI_API_INVALID_PTR = -2, /**< Invalid pointer */
  57         TAPI_API_NOT_SUPPORTED = -3, /**< The feature corresponding to the requested API is not supported. This may be due to market/network/vendor reasons such as the feature is not available in the network */
  58         TAPI_API_DEPRICATED = -4, /**< This API is deprecated and will be so in the future also */
  59         TAPI_API_SYSTEM_OUT_OF_MEM = -5, /**< Out of memory */
  60         TAPI_API_SYSTEM_RPC_LINK_DOWN = -6, /**< RPC link down */
  61         TAPI_API_SERVICE_NOT_READY = -7, /**< Phone is powered on, but is still to receive the power up completed notification */
  62         TAPI_API_SERVER_FAILURE = -8, /**< Error occurred in the Telephony server */
  63         TAPI_API_OEM_PLUGIN_FAILURE = -9, /**< Plug-in layer failure */
  64         TAPI_API_TRANSPORT_LAYER_FAILURE = -10, /**< Transport layer Failure */
  65         TAPI_API_INVALID_DATA_LEN = -11, /**< Invalid data length */
  66         TAPI_API_REQUEST_MAX_IN_PROGRESS = -12, /**< Maximum number of API Requests for the same service are already in progress */
  67         TAPI_API_OFFLINE_MODE_ERROR = -13, /**< OEM Telephony Provider is in the Offline mode */
  68         TAPI_EVENT_CLASS_UNKNOWN = -14, /**< Event class specified is not present in the Event Class list */
  69         TAPI_EVENT_UNKNOWN = -15, /**< Event specified is not present in the TAPI Unsolicited Event list */
  70         TAPI_REGISTRATION_OP_FAILED = -16, /**< Callback Registration/De-registration failed */
  71         TAPI_API_OPERATION_FAILED = -17, /**< API operation failed */
  72         TAPI_API_INVALID_OPERATION = -18, /**< API Invalid Operation */
  73         TAPI_API_ACCESS_DENIED = -19, /**< Access Denied */
  74
  75         TAPI_API_SYSTEM_RPC_LINK_NOT_EST = -100, /**< RPC link down */
  76         TAPI_API_API_NOT_SUPPORTED = -101, /**< API not supported */
  77         TAPI_API_SERVER_LAYER_FAILURE = -102, /**< Server layer failure */
  78
  79         /*      CALL */
  80         TAPI_API_INVALID_CALL_ID = -200, /**< Invalid call ID */
  81         TAPI_API_CALL_CTXT_OVERFLOW = -201, /**< Call context overflow */
  82         TAPI_API_COULD_NOT_GET_CALL_CTXT = -202, /**< Could not get the call context */
  83         TAPI_API_CTXT_SEARCH_RET_NON_CALL_CTXT = -203, /**< Context search returned the non-call context */
  84         TAPI_API_COULD_NOT_DESTROY_CTXT = -204, /**< Could not destroy the context */
  85         TAPI_API_INVALID_LINE_ID = -205, /**< Invalid line ID */
  86         TAPI_API_INVALID_CALL_HANDLE = -206, /**< Invalid call handle */
  87         TAPI_API_INVALID_CALL_STATE = -207, /**< Invalid call state - Newly added. Need to raise a CR for this */
  88         TAPI_API_CALL_PRE_COND_FAILED = -208, /**< Pre condition like MO call cannot be established now */
  89         TAPI_API_CALL_SAME_REQ_PENDING = -209, /**< Cannot accept the same request multiple times */
  90
  91         /*      POWER   */
  92         TAPI_API_MODEM_POWERED_OFF = -300, /**< Modem is powered off */
  93         TAPI_API_MODEM_ALREADY_ON = -301, /**< Modem is already on */
  94         TAPI_API_MODEM_ALREADY_OFF = -302, /**< Modem is already off */
  95
  96         /* NETTEXT */
  97         TAPI_API_NETTEXT_DEVICE_NOT_READY = -400, /**< Nettext device is not ready */
  98         TAPI_API_NETTEXT_SCADDR_NOT_SET = -401, /**< Nettext SCA address is not set */
  99         TAPI_API_NETTEXT_INVALID_DATA_LEN = -402, /**< Nettext Invalid data length */
 100         TAPI_NETTEXT_SCADDRESS_NOT_SET = -403, /**< Nettext SCA address is not set */
 101
 102         /* SIM  */
 103         TAPI_API_SIM_CARD_ERROR = -500, /**< SIM general error */
 104         TAPI_API_SIM_NOT_FOUND = -501, /**< SIM is not present / removed */
 105         TAPI_API_SIM_NOT_INITIALIZED = -502, /**< SIM has not initialized yet (waiting for PIN verification) */
 106         TAPI_API_SIM_LOCKED = -503, /**< PIN/PUK/NCK/NSCK/SPCK/CCK required state */
 107         TAPI_API_SIM_PERM_BLOCKED = -504, /**< SIM Permanently blocked state (no more allowing PUK input) */
 108         TAPI_API_SIM_SERVICE_IS_DISABLED = -505, /**< Service is disabled in EF-SST due to a given operation */
 109
 110         /* SAT  */
 111         TAPI_API_SAT_INVALID_COMMAND_ID = -600, /**< Command Number Invalid     */
 112         TAPI_API_SAT_COMMAND_TYPE_MISMATCH = -601, /**< Command Type Mismatch */
 113         TAPI_API_SAT_EVENT_NOT_REQUIRED_BY_USIM = -602, /**< Event Not Requested by the USIM */
 114
 115         /* Network */
 116         TAPI_API_NETWORK_INVALID_CTXT = -700, /**< Network invalid contex t*/
 117         TAPI_API_NETWORK_PLMN_NOT_ALLOWED = -701,         /** 3GPP Attache reject cause 11 */
 118         TAPI_API_NETWORK_ROAMING_NOT_ALLOWED = -702, /** 3GPP Attache reject cause 13 */
 119
 120         /*Misc */
 121         TAPI_API_MISC_RETURN_NULL = -800, /**< MISC return NULL */
 122         TAPI_API_MISC_VALIDITY_ERROR = -801, /**< MISC validity error */
 123         TAPI_API_MISC_INPUTPARM_ERROR = -802, /**< MISC input parameter error */
 124         TAPI_API_MISC_OUTPARAM_NULL = -803, /**< MISC output parameter NULL */
 125 } TapiResult_t;
 126
 127 /**
 128  * @brief Checks the 'scalar_exp' for TRUE, if failed then it returns 'err_value' from the function.
 129  */
 130 #define TAPI_RET_ERR_NUM_IF_FAIL(scalar_exp, err_num) {\
 131         if (!(scalar_exp)) \
 132         { \
 133                 err("TAPI_RET_ERR_NUM_IF_FAIL Failed. returning [%d]", err_num);\
 134                 return err_num; \
 135         } \
 136 }
 137
 138 /**
 139  * @brief Returns from the current function if the expression is not true.
 140  * @details If the expression evaluates to FALSE, a critical message is logged and the function returns.
 141  *          This can only be used in functions which do not return a value.
 142  *
 143  * @param[in] scalar_exp The expression to check
 144  */
 145 #define TAPI_RETURN_IF_FAIL(scalar_exp) {\
 146         if (!scalar_exp) \
 147         { \
 148                 err("TAPI_RETURN_IF_FAIL: Failed: Returning from here."); \
 149                 return; \
 150         } \
 151 }
 152
 153 /**
 154  * @brief Returns from the current function, returning the value @a ret, if the expression is not true.
 155  * @details If the expression evaluates to FALSE, a critical message is logged and @a ret is returned.
 156  */
 157 #define TAPI_RETURN_VAL_IF_FAIL(scalar_exp, ret) { \
 158         if (!scalar_exp) \
 159         { \
 160                 err("TAPI_RETURN_VAL_IF_FAIL: Failed: Returning [%d]", ret); \
 161                 return ret; \
 162         } \
 163 }
 164
 165 /**
 166  * @brief Returns from the current function, returning the value @a ret, if the expression is not true.
 167  * @details If the expression evaluates to FALSE, a critical message is logged and @a ret is returned.
 168  */
 169 #define TAPI_RETURN_VAL_IF_SUCCESS(scalar_exp, ret) { \
 170         if (scalar_exp) \
 171         { \
 172                 err("TAPI_RETURN_VAL_IF_SUCCESS: Failed Returning [%d]", ret); \
 173                 return ret; \
 174         } \
 175 }
 176
 177 /**
 178  * @brief Logs an error on stderr and abort, if assertion failed.
 179  * @details Use this only if the telephpny sevrer needs to be exited, if asertion fails.
 180  */
 181 #define TAPI_ASSERT(scalar_exp) assert(scalar_exp);
 182
 183 /**
 184  * @brief Returns from the current function, returning the value @a ret, if @a exp1 and @a exp2 are of the same value.
 185  * @details If the equal expression evaluates to TRUE, a critical message is logged and @a ret is returned.
 186  */
 187 #define TAPI_RETURN_VAL_IF_EQUAL(exp1, exp2, ret) {     \
 188         if (exp1 == exp2) \
 189         { \
 190                 err("TAPI_RETURN_VAL_IF_EQUAL: FAILED, Returning [%d]", ret); \
 191                 return ret; \
 192         } \
 193 }
 194
 195 /**
 196  * @brief Allocates a region of the memory, which is large enough to hold n elements of size bytes each.
 197  * @details The allocated region is initialized to zero.
 198  */
 199 #define TAPI_CALLOC(ptr, no_elements, type)     \
 200         ptr = (type *) calloc (no_elements , sizeof (type)); \
 201         if (ptr == NULL) { \
 202                 perror("NULL is returned"); \
 203                 err("calloc error -NULL, errno is [%d]", errno); \
 204                 TAPI_ASSERT(ptr); \
 205         }
 206
 207 /**
 208  * @brief Deletes a pointer with double free check.
 209  * @details If the same pointer is passed to free twice, known as a double free.
 210  *          To avoid this, set pointers to NULL after passing them to free: free(NULL) is safe (it does nothing).
 211  */
 212 #define TAPI_FREE(ptr) \
 213         if (ptr != NULL) { \
 214                 free(ptr); \
 215                 ptr = NULL; \
 216         } \
 217         else { \
 218                 err("Double Free or NULL"); \
 219         }
 220
 221 /**
 222  * @brief Checks for available destination buffer size before copying source buffer data to the destination buffer.
 223  * @details It asserts if the destination buffer size is less than the source buffer size.
 224  */
 225 #define TAPI_MEMCPY(dest, src, dest_len, src_len) \
 226         if (dest_len >= src_len) { \
 227                 memcpy(dest, src, src_len); \
 228         } \
 229         else { \
 230                 err("TAPI_MEMCPY FAILURE - dest_len(%d) < src_len(%d)", dest_len, src_len); \
 231                 assert(0); \
 232         }
 233
 234 /**
 235  * @brief Encodes a sequence of binary data into its Base-64 stringified representation.
 236  *
 237  * @param[in] data The binary data to encode
 238  * @param[in] len The length of data
 239  * @param[out] encoded_data The encoded data
 240  * @return A newly allocated, zero-terminated Base-64 encoded string representing data
 241  */
 242 #define TAPI_BASE64_ENCODE(data, len, encoded_data) \
 243         encoded_data = g_base64_encode((const guchar *)data, (gsize) len);
 244
 245 /**
 246  * @brief Decodes a sequence of Base-64 encoded text into binary data.
 247  *
 248  * @param[in] text The zero-terminated string with base64 text to decode
 249  * @param[out] decoded_data The decoded data
 250  * @param[in] ptr_out_len The length of the decoded data
 251  * @return A newly allocated buffer containing the binary data representing text
 252  */
 253 #define TAPI_BASE64_DECODE(text, decoded_data, ptr_out_len)     \
 254         decoded_data = g_base64_decode((const gchar *)text, (gsize *)ptr_out_len);
 255
 256 /**
 257  * @brief Calculates the length of SCA in BCD type.
 258  */
 259 #define TAPI_GET_LENGTH_FROM_BCD(nLength, rtn) { \
 260         if (nLength <= 0) { \
 261                 rtn = 0; \
 262         } \
 263         else if ((nLength) % 2) { \
 264                 rtn = ((nLength) / 2) + 1; \
 265         } \
 266         else { \
 267                 rtn = (nLength) / 2; \
 268         } \
 269 }
 270
 271
 272 #define TAPI_VALIDATE_EVENTTYPE(val_min ,val_max, type, ret) { \
 273         if (type < val_min || type > val_max ) { \
 274                 return ret; \
 275         } \
 276 }
 277
 278 __END_DECLS
 279
 280 #endif //_TEL_UTILITY_H_
 281 /**
 282  * @}
 283  */