mobile/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 error/blocked state */
  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,
  98
  99         /* SAT  */
 100         TAPI_API_SAT_INVALID_COMMAND_ID = -600, /**<Command Number Invalid      */
 101         TAPI_API_SAT_COMMAND_TYPE_MISMATCH = -601, /**< Command Type Mismatch   */
 102         TAPI_API_SAT_EVENT_NOT_REQUIRED_BY_USIM = -602, /**< Event Not Requested by USIM*/
 103
 104         /* Network */
 105         TAPI_API_NETWORK_INVALID_CTXT = -700, /**< Network invalid context*/
 106
 107         /*Misc */
 108         TAPI_API_MISC_RETURN_NULL = -800, /**< MISC return NULL*/
 109         TAPI_API_MISC_VALIDITY_ERROR = -801, /**< MISC validity error*/
 110         TAPI_API_MISC_INPUTPARM_ERROR = -802, /**< MISC input parameter error*/
 111         TAPI_API_MISC_OUTPARAM_NULL = -803, /**< MISC output parameter null*/
 112 } TapiResult_t;
 113
 114 /**
 115  * This will check the 'scalar_exp' for TRUE, if failed then return 'err_value' from function.
 116  */
 117 #define TAPI_RET_ERR_NUM_IF_FAIL(scalar_exp, err_num) {\
 118         if (!(scalar_exp)) \
 119         { \
 120                 err("TAPI_RET_ERR_NUM_IF_FAIL Failed. returning [%d]", err_num);\
 121                 return err_num; \
 122         } \
 123 }
 124
 125 /**
 126  * Returns from the current function if the expression is not true. If the expression evaluates to FALSE,
 127  * a critical message is logged and the function returns. This can only be used in functions which do not
 128  * return a value.
 129  *
 130  * expr : the expression to check.
 131  */
 132 #define TAPI_RETURN_IF_FAIL(scalar_exp) {\
 133         if (!scalar_exp) \
 134         { \
 135                 err("TAPI_RETURN_IF_FAIL: Failed: Returning from here."); \
 136                 return; \
 137         } \
 138 }
 139
 140 /**
 141  * Returns from the current function, returning the value ret, if the expression is not true.
 142  * If the expression evaluates to FALSE, a critical message is logged and ret is returned.
 143  */
 144 #define TAPI_RETURN_VAL_IF_FAIL(scalar_exp, ret) { \
 145         if (!scalar_exp) \
 146         { \
 147                 err("TAPI_RETURN_VAL_IF_FAIL: Failed: Returning [%d]", ret); \
 148                 return ret; \
 149         } \
 150 }
 151
 152 /**
 153  * Returns from the current function, returning the value ret, if the expression is not true.
 154  * If the expression evaluates to FALSE, a critical message is logged and ret is returned.
 155  */
 156 #define TAPI_RETURN_VAL_IF_SUCCESS(scalar_exp, ret) { \
 157         if (scalar_exp) \
 158         { \
 159                 err("TAPI_RETURN_VAL_IF_SUCCESS: Failed Returning [%d]", ret); \
 160                 return ret; \
 161         } \
 162 }
 163
 164 /**
 165  * This assert will log an err on stderr and abort,  if assertion failed,
 166  * Use this only if the telephpny sevrer needs to be exited, if asertion fails
 167  */
 168 #define TAPI_ASSERT(scalar_exp) assert(scalar_exp);
 169
 170 /**
 171  * Returns from the current function, returning the value ret, if the exp1 and exp2 are of same value.
 172  * If the equal expression evaluates to TRUE, a critical message is logged and ret is returned.
 173  */
 174 #define TAPI_RETURN_VAL_IF_EQUAL(exp1, exp2, ret) {     \
 175         if (exp1 == exp2) \
 176         { \
 177                 err("TAPI_RETURN_VAL_IF_EQUAL: FAILED, Returning [%d]", ret); \
 178                 return ret; \
 179         } \
 180 }
 181
 182 /**
 183  * void *calloc(size_t nelements, size_t bytes);
 184  * which allocates a region of memory large enough to hold nelements of size bytes each.
 185  * The allocated region is initialized to zero.
 186  */
 187 #define TAPI_CALLOC(ptr, no_elements, type)     \
 188         ptr = (type *) calloc (no_elements , sizeof (type)); \
 189         if (ptr == NULL) { \
 190                 perror("NULL is returned"); \
 191                 err("calloc error -NULL, errno is [%d]", errno); \
 192                 fprintf(stderr,"Calloc ERRNO %d\n", errno); \
 193                 TAPI_ASSERT(ptr); \
 194         }
 195
 196 /**
 197  * why ptr = NULL; after free()?.
 198  * If the same pointer is passed to free twice, known as a double free. To avoid this, set pointers to
 199  * NULL after passing them to free: free(NULL) is safe (it does nothing).
 200  */
 201 #define TAPI_FREE(ptr) \
 202         if (ptr != NULL) { \
 203                 free(ptr); \
 204                 ptr = NULL; \
 205         } \
 206         else { \
 207                 err("Double Free or NULL"); \
 208         }
 209
 210 /**
 211  * check for available destination buffer size before copying source buffer data to destination buffer.
 212  * Assert if destination buffer size less than source buffer size.
 213  */
 214 #define TAPI_MEMCPY(dest, src, dest_len, src_len) \
 215         if (dest_len >= src_len) { \
 216                 memcpy(dest, src, src_len); \
 217         } \
 218         else { \
 219                 err("TAPI_MEMCPY FAILURE - dest_len(%d) < src_len(%d)", dest_len, src_len); \
 220                 assert(0); \
 221         }
 222
 223 /**
 224  * Encode a sequence of binary data into its Base-64 stringified representation.
 225  *
 226  * data : the binary data to encode.
 227  * len : the length of data.
 228  * Returns : a newly allocated, zero-terminated Base-64 encoded string representing data.
 229  * gchar *g_base64_encode (const guchar *data, gsize len);
 230  */
 231 #define TAPI_BASE64_ENCODE(data, len, encoded_data) \
 232         encoded_data = g_base64_encode((const guchar *)data, (gsize) len);
 233
 234 /**
 235  * Decode a sequence of Base-64 encoded text into binary data
 236  *
 237  * text : zero-terminated string with base64 text to decode.
 238  * out_len : The length of the decoded data is written here.
 239  * Returns : a newly allocated buffer containing the binary data that text represents
 240  * guchar *g_base64_decode  (const gchar *text, gsize *out_len);
 241  */
 242 #define TAPI_BASE64_DECODE(text, decoded_data, ptr_out_len)     \
 243         decoded_data = g_base64_decode((const gchar *)text, (gsize *)ptr_out_len);
 244
 245 /**
 246  * Define Macro for calculate the length of SCA in BCD type.
 247  */
 248 #define TAPI_GET_LENGTH_FROM_BCD(nLength, rtn) { \
 249         if (nLength <= 0) { \
 250                 rtn = 0; \
 251         } \
 252         else if ((nLength) % 2) { \
 253                 rtn = ((nLength) / 2) + 1; \
 254         } \
 255         else { \
 256                 rtn = (nLength) / 2; \
 257         } \
 258 }
 259
 260
 261 #define TAPI_VALIDATE_EVENTTYPE(val_min ,val_max, type, ret) { \
 262         if (type < val_min || type > val_max ) { \
 263                 return ret; \
 264         } \
 265 }
 266
 267 __END_DECLS
 268
 269 #endif //_TEL_UTILITY_H_
 270 /**
 271  * @}
 272  */