include/serial.h

   1 /*
   2 * Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 #ifndef __TIZEN_NETWORK_SERIAL_H__
  18 #define __TIZEN_NETWORK_SERIAL_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26
  27 /**
  28 * @addtogroup CAPI_NETWORK_SERIAL_MODULE
  29 * @{
  30 */
  31
  32
  33 /**
  34 * @brief The handle of serial
  35 */
  36 typedef void* serial_h;
  37
  38 /**
  39 * @brief Enumerations for the state of serial
  40 */
  41 typedef enum
  42 {
  43     SERIAL_STATE_OPENED = 0,  /**< Opened */
  44     SERIAL_STATE_CLOSED = 1,  /**< Closed */
  45 } serial_state_e;
  46
  47 /**
  48 * @brief Enumerations for error code
  49 */
  50 typedef enum
  51 {
  52     SERIAL_ERROR_NONE = TIZEN_ERROR_NONE,  /**< Successful */
  53     SERIAL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,  /**< Out of memory */
  54     SERIAL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  55     SERIAL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,  /**< Invalid operation */
  56     SERIAL_ERROR_OPERATION_FAILED = TIZEN_ERROR_NETWORK_CLASS|0x0601,  /**< Operation failed */
  57 } serial_error_e;
  58
  59 /**
  60 * @brief  Called when you receive data.
  61 * @remarks  @a data is valid only in this function.
  62 * @param[in]  data  The received data
  63 * @param[in]  user_data  The user data passed from serial_set_data_received_cb()
  64 * @pre  If you register callback function using serial_set_data_received_cb(), this will be invoked when you receive data.
  65 * @see  serial_set_data_received_cb()
  66 * @see  serial_unset_data_received_cb()
  67 */
  68 typedef bool (*serial_data_received_cb)(const char *data, int data_length, void *user_data);
  69
  70 /**
  71 * @brief  Called when the state of serial is changed.
  72 * @param[in]  result  The result of opening the serial
  73 * @param[in]  state  The state of serial
  74 * @param[in]  user_data  The user data passed from serial_set_state_changed_cb()
  75 * @pre  If you register callback function using serial_set_state_changed_cb(), this will be invoked when the state of serial is changed.
  76 * @see  serial_set_state_changed_cb()
  77 * @see  serial_unset_state_changed_cb()
  78 */
  79 typedef void (*serial_state_changed_cb)(serial_error_e result, serial_state_e state, void *user_data);
  80
  81
  82 /**
  83 * @brief  Creates the handle of serial.
  84 * @param[out]  serial  The serial handle
  85 * @return  0 on success, otherwise a negative error value.
  86 * @retval  #SERIAL_ERROR_NONE  Successful
  87 * @retval  #SERIAL_ERROR_OUT_OF_MEMORY  Out of memory
  88 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
  89 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
  90 * @see  serial_destroy()
  91 */
  92 int serial_create(serial_h *serial);
  93
  94 /**
  95 * @brief  Destroys the handle of serial.
  96 * @param[in]  serial  The serial handle
  97 * @return  0 on success, otherwise a negative error value.
  98 * @retval  #SERIAL_ERROR_NONE  Successful
  99 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 100 * @see  serial_create()
 101 */
 102 int serial_destroy(serial_h serial);
 103
 104 /**
 105 * @brief  Opens the serial.
 106 * @param[in]  serial  The serial handle
 107 * @return  0 on success, otherwise a negative error value.
 108 * @retval  #SERIAL_ERROR_NONE  Successful
 109 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 110 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 111 * @retval  #SERIAL_ERROR_INVALID_OPERATION  Invalid operation
 112 * @post  When a serial is opened, serial_state_changed_cb() will be called with #SERIAL_STATE_OPENED state
 113 * @see  serial_close()
 114 */
 115 int serial_open(serial_h serial);
 116
 117 /**
 118 * @brief  Closes the serial.
 119 * @param[in]  serial  The serial handle
 120 * @return  0 on success, otherwise a negative error value.
 121 * @retval  #SERIAL_ERROR_NONE  Successful
 122 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 123 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 124 * @retval  #SERIAL_ERROR_INVALID_OPERATION  Invalid operation
 125 * @pre  The serial must be opened.
 126 * @post  When a serial is closed, serial_state_changed_cb() will be called with #SERIAL_STATE_CLOSED state
 127 * @see  serial_open()
 128 */
 129 int serial_close(serial_h serial);
 130
 131 /**
 132 * @brief  Writes data to serial server.
 133 * @param[in]  serial  The serial handle
 134 * @param[in]  data The data to send
 135 * @param[in]  data_length The length of data to send
 136 * @return  The number of characters sent on success, otherwise a negative error value.
 137 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 138 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 139 * @pre  The serial must be opened.
 140 * @see  serial_open()
 141 */
 142 int serial_write(serial_h serial, const char *data, int data_length);
 143
 144 /**
 145 * @brief  Register a callback function to be invoked when you receive data.
 146 * @param[in]  serial  The serial handle
 147 * @param[in]  callback  The callback function to be invoked
 148 * @param[in]  user_data  The user data to be passed to the callback function
 149 * @return  0 on success, otherwise a negative error value.
 150 * @retval  #SERIAL_ERROR_NONE  Successful
 151 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 152 * @post  serial_data_received_cb() will be invoked when you receive data.
 153 * @see  serial_unset_data_received_cb()
 154 * @see  serial_data_received_cb()
 155 */
 156 int serial_set_data_received_cb(serial_h serial, serial_data_received_cb callback, void *user_data);
 157
 158 /**
 159 * @brief  Unregister a callback function to be invoked when you receive data.
 160 * @param[in]  serial  The serial handle
 161 * @return   0 on success, otherwise a negative error value.
 162 * @retval  #SERIAL_ERROR_NONE  Successful
 163 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 164 * @see  serial_set_data_received_cb()
 165 */
 166 int serial_unset_data_received_cb(serial_h serial);
 167
 168 /**
 169 * @brief  Register a callback function to be invoked when the state of serial is changed.
 170 * @param[in]  serial  The serial handle
 171 * @param[in]  callback  The callback function to be invoked
 172 * @param[in]  user_data  The user data to be passed to the callback function
 173 * @return   0 on success, otherwise a negative error value.
 174 * @retval  #SERIAL_ERROR_NONE  Successful
 175 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 176 * @post  serial_state_changed_cb() will be invoked when the state of serial is changed.
 177 * @see  serial_unset_state_changed_cb()
 178 * @see  serial_state_changed_cb()
 179 */
 180 int serial_set_state_changed_cb(serial_h serial, serial_state_changed_cb callback, void *user_data);
 181
 182 /**
 183 * @brief  Unregister a callback function to be invoked when the state of serial is changed.
 184 * @param[in]  serial  The serial handle
 185 * @return   0 on success, otherwise a negative error value.
 186 * @retval  #SERIAL_ERROR_NONE  Successful
 187 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 188 * @see  serial_set_state_changed_cb()
 189 */
 190 int serial_unset_state_changed_cb(serial_h serial);
 191
 192 /**
 193 * @}
 194 */
 195
 196
 197 #ifdef __cplusplus
 198 }
 199 #endif
 200
 201 #endif /* __TIZEN_NETWORK_SERIAL_H__ */