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 * @addtogroup CAPI_NETWORK_SERIAL_MODULE
  28 * @{
  29 */
  30
  31 /**
  32 * @brief The handle of serial
  33 */
  34         typedef void *serial_h;
  35
  36 /**
  37 * @brief Enumerations for the state of serial
  38 */
  39         typedef enum {
  40                 SERIAL_STATE_OPENED = 0,
  41                                                           /**< Opened */
  42                 SERIAL_STATE_CLOSED = 1,
  43                                                           /**< Closed */
  44         } serial_state_e;
  45
  46 /**
  47 * @brief Enumerations for error code
  48 */
  49         typedef enum {
  50                 SERIAL_ERROR_NONE = TIZEN_ERROR_NONE,
  51                                                                                    /**< Successful */
  52                 SERIAL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,
  53                                                                                                                          /**< Out of memory */
  54                 SERIAL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
  55                                                                                                                                          /**< Invalid parameter */
  56                 SERIAL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,
  57                                                                                                                                          /**< Invalid operation */
  58                 SERIAL_ERROR_OPERATION_FAILED = TIZEN_ERROR_NETWORK_CLASS | 0x0601,
  59                                                                                                                                            /**< Operation failed */
  60         } serial_error_e;
  61
  62 /**
  63 * @brief  Called when you receive data.
  64 * @remarks  @a data is valid only in this function.
  65 * @param[in]  data  The received data
  66 * @param[in]  user_data  The user data passed from serial_set_data_received_cb()
  67 * @pre  If you register callback function using serial_set_data_received_cb(), this will be invoked when you receive data.
  68 * @see  serial_set_data_received_cb()
  69 * @see  serial_unset_data_received_cb()
  70 */
  71         typedef bool(*serial_data_received_cb) (const char *data, int data_length, void *user_data);
  72
  73 /**
  74 * @brief  Called when the state of serial is changed.
  75 * @param[in]  result  The result of opening the serial
  76 * @param[in]  state  The state of serial
  77 * @param[in]  user_data  The user data passed from serial_set_state_changed_cb()
  78 * @pre  If you register callback function using serial_set_state_changed_cb(), this will be invoked when the state of serial is changed.
  79 * @see  serial_set_state_changed_cb()
  80 * @see  serial_unset_state_changed_cb()
  81 */
  82         typedef void (*serial_state_changed_cb) (serial_error_e result, serial_state_e state, void *user_data);
  83
  84 /**
  85 * @brief  Creates the handle of serial.
  86 * @param[out]  serial  The serial handle
  87 * @return  0 on success, otherwise a negative error value.
  88 * @retval  #SERIAL_ERROR_NONE  Successful
  89 * @retval  #SERIAL_ERROR_OUT_OF_MEMORY  Out of memory
  90 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
  91 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
  92 * @see  serial_destroy()
  93 */
  94         int serial_create(serial_h * serial);
  95
  96 /**
  97 * @brief  Destroys the handle of serial.
  98 * @param[in]  serial  The serial handle
  99 * @return  0 on success, otherwise a negative error value.
 100 * @retval  #SERIAL_ERROR_NONE  Successful
 101 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 102 * @see  serial_create()
 103 */
 104         int serial_destroy(serial_h serial);
 105
 106 /**
 107 * @brief  Opens the serial.
 108 * @param[in]  serial  The serial handle
 109 * @return  0 on success, otherwise a negative error value.
 110 * @retval  #SERIAL_ERROR_NONE  Successful
 111 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 112 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 113 * @retval  #SERIAL_ERROR_INVALID_OPERATION  Invalid operation
 114 * @post  When a serial is opened, serial_state_changed_cb() will be called with #SERIAL_STATE_OPENED state
 115 * @see  serial_close()
 116 */
 117         int serial_open(serial_h serial);
 118
 119 /**
 120 * @brief  Closes the serial.
 121 * @param[in]  serial  The serial handle
 122 * @return  0 on success, otherwise a negative error value.
 123 * @retval  #SERIAL_ERROR_NONE  Successful
 124 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 125 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 126 * @retval  #SERIAL_ERROR_INVALID_OPERATION  Invalid operation
 127 * @pre  The serial must be opened.
 128 * @post  When a serial is closed, serial_state_changed_cb() will be called with #SERIAL_STATE_CLOSED state
 129 * @see  serial_open()
 130 */
 131         int serial_close(serial_h serial);
 132
 133 /**
 134 * @brief  Writes data to serial server.
 135 * @param[in]  serial  The serial handle
 136 * @param[in]  data The data to send
 137 * @param[in]  data_length The length of data to send
 138 * @return  The number of characters sent on success, otherwise a negative error value.
 139 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 140 * @retval  #SERIAL_ERROR_OPERATION_FAILED  Operation failed
 141 * @pre  The serial must be opened.
 142 * @see  serial_open()
 143 */
 144         int serial_write(serial_h serial, const char *data, int data_length);
 145
 146 /**
 147 * @brief  Register a callback function to be invoked when you receive data.
 148 * @param[in]  serial  The serial handle
 149 * @param[in]  callback  The callback function to be invoked
 150 * @param[in]  user_data  The user data to be passed to the callback function
 151 * @return  0 on success, otherwise a negative error value.
 152 * @retval  #SERIAL_ERROR_NONE  Successful
 153 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 154 * @post  serial_data_received_cb() will be invoked when you receive data.
 155 * @see  serial_unset_data_received_cb()
 156 * @see  serial_data_received_cb()
 157 */
 158         int serial_set_data_received_cb(serial_h serial, serial_data_received_cb callback, void *user_data);
 159
 160 /**
 161 * @brief  Unregister a callback function to be invoked when you receive data.
 162 * @param[in]  serial  The serial handle
 163 * @return   0 on success, otherwise a negative error value.
 164 * @retval  #SERIAL_ERROR_NONE  Successful
 165 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 166 * @see  serial_set_data_received_cb()
 167 */
 168         int serial_unset_data_received_cb(serial_h serial);
 169
 170 /**
 171 * @brief  Register a callback function to be invoked when the state of serial is changed.
 172 * @param[in]  serial  The serial handle
 173 * @param[in]  callback  The callback function to be invoked
 174 * @param[in]  user_data  The user data to be passed to the callback function
 175 * @return   0 on success, otherwise a negative error value.
 176 * @retval  #SERIAL_ERROR_NONE  Successful
 177 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 178 * @post  serial_state_changed_cb() will be invoked when the state of serial is changed.
 179 * @see  serial_unset_state_changed_cb()
 180 * @see  serial_state_changed_cb()
 181 */
 182         int serial_set_state_changed_cb(serial_h serial, serial_state_changed_cb callback, void *user_data);
 183
 184 /**
 185 * @brief  Unregister a callback function to be invoked when the state of serial is changed.
 186 * @param[in]  serial  The serial handle
 187 * @return   0 on success, otherwise a negative error value.
 188 * @retval  #SERIAL_ERROR_NONE  Successful
 189 * @retval  #SERIAL_ERROR_INVALID_PARAMETER  Invalid parameter
 190 * @see  serial_set_state_changed_cb()
 191 */
 192         int serial_unset_state_changed_cb(serial_h serial);
 193
 194 /**
 195 * @}
 196 */
 197
 198 #ifdef __cplusplus
 199 }
 200 #endif
 201 #endif                                                  /* __TIZEN_NETWORK_SERIAL_H__ */