wearable/include/TapiUtility.h

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