include/usb_accessory.h

   1 /*
   2  * usb-accessory
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #ifndef __TIZEN_SYSTEM_USB_ACCESSORY_H__
  19 #define __TIZEN_SYSTEM_USB_ACCESSORY_H__
  20
  21 #include <stdio.h>
  22 #include <tizen.h>
  23
  24 /**
  25  * @addtogroup CAPI_SYSTEM_USB_ACCESSORY_MODULE
  26  * @{
  27  */
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @brief Enumerations of error code for usb accessory.
  35  */
  36 typedef enum
  37 {
  38     USB_ERROR_NONE              = TIZEN_ERROR_NONE,
  39     USB_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
  40     USB_ERROR_NOT_CONNECTED     = TIZEN_ERROR_ENDPOINT_NOT_CONNECTED,
  41     USB_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,
  42     USB_ERROR_OPERATION_FAILED  = TIZEN_ERROR_SYSTEM_CLASS | 0x62,
  43     USB_ERROR_IPC_FAILED        = TIZEN_ERROR_PROTOCOL_NOT_AVALIABLE,
  44     USB_ERROR_NOT_SUPPORTED     = TIZEN_ERROR_NOT_SUPPORT_API
  45 } usb_error_e;
  46
  47 /**
  48  * @brief The USB Accessory handle.
  49  */
  50 typedef struct usb_accessory_s* usb_accessory_h;
  51
  52 /**
  53  * @brief Called when the usb accessory is connected or disconnected.
  54  *
  55  * @remark
  56  * the handle of accessory will be free after end of usb_accessory_connection_cb()
  57  *
  58  * @param[in] accessory     The handle of the attached usb accessory.
  59  * @param[in] is_connected   True when connected or False when connection is lost.
  60  * @param[in] data          The user data passed from the register function.
  61  *
  62  * @see usb_accessory_connection_set_cb()
  63  */
  64 typedef void (*usb_accessory_connection_changed_cb)(usb_accessory_h accessory, bool is_connected, void *data);
  65
  66 /**
  67  * @brief Called when the permission of usb accessory is granted.
  68  *
  69  * @remark
  70  * the handle of accessory will be free after end of usb_accessory_request_permission_cb()
  71  *
  72  * @param[in] accessory     The handle of the attached usb accessory.
  73  * @param[in] is_granted     The permission of usb accessory.
  74  *
  75  * @see usb_accessory_request_permission()
  76  */
  77 typedef void (*usb_accessory_permission_response_cb)(usb_accessory_h accessory, bool is_granted);
  78
  79 /**
  80  * @brief Called to retrieve the handles of usb accessory.
  81  *
  82  * @remark
  83  * the handle of accessory will be free after end of usb_accessory_attached_cb()
  84  *
  85  * @param[in] handle        The handle of the attached usb accessory.
  86  * @param[in] data          The user data passed from the foreach function.
  87  *
  88  * @return                  @c true to continue with the next iteration of the loop, \n
  89  *                          @c false to break out of the loop.
  90  *
  91  * @see usb_accessory_foreach_attached()
  92  */
  93 typedef bool (*usb_accessory_attached_cb)(usb_accessory_h handle, void *data);
  94
  95 /**
  96  * @brief Clone the handle of usb accessory.
  97  *
  98  * @remark
  99  * the cloned handle must be destroyed by #usb_accessory_destroy()
 100  *
 101  * @param[in]  handle           The usb accessory handle that want to copy.
 102  * @param[out] cloned_handle    The cloned usb accessory handle.
 103  *
 104  * @return                  0 on success, otherwise a negative error value
 105  * @retval                  #USB_ERROR_NONE                 Successful
 106  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 107  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 108  *
 109  * @see usb_accessory_destroy()
 110  */
 111 int usb_accessory_clone(usb_accessory_h handle, usb_accessory_h* cloned_handle);
 112
 113 /**
 114  * @brief Destroy the handle of usb accessory.
 115  *
 116  * @param[in] handle        The handle of the attached usb accessory.
 117  *
 118  * @return                  0 on success, otherwise a negative error value
 119  * @retval                  #USB_ERROR_NONE                 Successful
 120  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 121  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 122  */
 123 int usb_accessory_destroy(usb_accessory_h handle);
 124
 125 /**
 126  * @brief Retrieves every attached usb accessory handles.
 127  * @details
 128  * usb_accessory_attached_cb() will be called once for each handle of attached usb accessory.
 129  * if usb_accessory_attached_cb() callback function returns false, then iteration will be finished.
 130  *
 131  * @remark
 132  * the handle of accessory will be free after end of usb_accessory_attached_cb().
 133  *
 134  * @param[in] callback      The iteration callback function.
 135  * @param[in] user_data     The user data to be passed to the callback function.
 136  *
 137  * @return                  0 on success, otherwise a negative error value
 138  * @retval                  #USB_ERROR_NONE                 Successful
 139  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 140  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 141  */
 142 int usb_accessory_foreach_attached(usb_accessory_attached_cb callback, void *user_data);
 143
 144 /**
 145  * @brief Register callback function to be invoked when usb accessory connected or disconnected.
 146  * @details
 147  * The handle of attached usb accessory handle will be passed to usb_accessory_connection_cb().
 148  * And status of connection will be also passed to callback function.
 149  *
 150  * @param[in] accessory     The attached usb accessory handle.
 151  * @param[in] callback      The callback function to register.
 152  * @param[in] user_data     The user data to be passed to the callback function.
 153  *
 154  * @return                  0 on success, otherwise a negative error value
 155  * @retval                  #USB_ERROR_NONE                 Successful
 156  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 157  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 158  *
 159  * @see usb_accessory_connection_unset_cb()
 160  *
 161  */
 162 int usb_accessory_set_connection_changed_cb(usb_accessory_connection_changed_cb callback, void* user_data);
 163
 164 /**
 165  * @brief Unregister the usb accessory connection callback function.
 166  *
 167  * @param[in] accessory     The attached usb accessory handle.
 168  *
 169  * @return                  0 on success, otherwise a negative error value
 170  * @retval                  #USB_ERROR_NONE                 Successful
 171  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 172  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 173  *
 174  * @see usb_accessory_connection_set_cb()
 175  */
 176 int usb_accessory_connection_unset_cb(void);
 177
 178 /**
 179  * @brief Check whether or not the accessory has permission to access to the host.
 180  *
 181  * @param[in]  accessory     The attached usb accessory handle.
 182  * @param[out] is_granted    The permission to access to the host.
 183  *
 184  * @return                  0 on success, otherwise a negative error value
 185  * @retval                  #USB_ERROR_NONE                 Successful
 186  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 187  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 188  */
 189 int usb_accessory_has_permission(usb_accessory_h accessory, bool *is_granted);
 190
 191 /**
 192  * @brief opens a file descriptor for reading and writing data to the usb accessory.
 193  *
 194  * @param[in]  accessory     The attached usb accessory handle.
 195  * @param[out] fd            opened File descriptor for usb accessory.
 196  *
 197  * @return                  0 on success, otherwise a negative error value
 198  * @retval                  #USB_ERROR_NONE                 Successful
 199  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 200  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 201  */
 202 int usb_accessory_open(usb_accessory_h accessory, FILE **fd);
 203
 204 /**
 205  * @brief Get description of the accessory.
 206  *
 207  * @param[in]  accessory     The attached usb accessory handle.
 208  * @param[out] description   The description of the usbaccessory.
 209  *
 210  * @return                  0 on success, otherwise a negative error value
 211  * @retval                  #USB_ERROR_NONE                 Successful
 212  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 213  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 214  */
 215 int usb_accessory_get_description(usb_accessory_h accessory, char** description);
 216
 217 /**
 218  * @brief Get manufacturer name of the accessory.
 219  *
 220  * @param[in]  accessory     The attached usb accessory handle.
 221  * @param[out] manufacturer  The name of manufacturer.
 222  *
 223  * @return                  0 on success, otherwise a negative error value
 224  * @retval                  #USB_ERROR_NONE                 Successful
 225  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 226  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 227  */
 228 int usb_accessory_get_manufacturer(usb_accessory_h accessory, char** manufacturer);
 229
 230 /**
 231  * @brief Get model name of the accessory.
 232  *
 233  * @param[in]  accessory     The attached usb accessory handle.
 234  * @param[out] model         The model name of usb accessory.
 235  *
 236  * @return                  0 on success, otherwise a negative error value
 237  * @retval                  #USB_ERROR_NONE                 Successful
 238  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 239  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 240  */
 241 int usb_accessory_get_model(usb_accessory_h accessory, char** model);
 242
 243 /**
 244  * @brief Get unique serial number of the accessory.
 245  *
 246  * @param[in]  accessory     The attached usb accessory handle.
 247  * @param[out] serial        The serial of usb accessory.
 248  *
 249  * @return                  0 on success, otherwise a negative error value
 250  * @retval                  #USB_ERROR_NONE                 Successful
 251  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 252  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 253  */
 254 int usb_accessory_get_serial(usb_accessory_h accessory, char** serial);
 255
 256 /**
 257  * @brief Get version of the accessory.
 258  *
 259  * @param[in]  accessory     The attached usb accessory handle.
 260  * @param[out] version       The version of usb accessory.
 261  *
 262  * @return                  0 on success, otherwise a negative error value
 263  * @retval                  #USB_ERROR_NONE                 Successful
 264  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 265  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 266  */
 267 int usb_accessory_get_version(usb_accessory_h accessory, char** version);
 268
 269 /**
 270  * @brief Check whether or not the connection of the usb accessory.
 271  *
 272  * @param[in]  accessory     The usb accessory handle to check.
 273  * @param[out] is_connected  The connection status.
 274  *
 275  * @return                  0 on success, otherwise a negative error value
 276  * @retval                  #USB_ERROR_NONE                 Successful
 277  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 278  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 279  */
 280 int usb_accessory_is_connected(usb_accessory_h accessory, bool *is_connected);
 281
 282 /**
 283  * @brief Request permission to user for usb accessory.
 284  * @details
 285  * The usb accessory handle and boolean passed to callback function that indicating whether permission was granted by the user.
 286  *
 287  * @param[in] accessory     The attached usb accessory handle.
 288  * @param[in] callback      The callback function to register.
 289  * @param[in] user_data     The user data to be passed to the callback function.
 290  *
 291  * @return                  0 on success, otherwise a negative error value
 292  * @retval                  #USB_ERROR_NONE                 Successful
 293  * @retval                  #USB_ERROR_INVALID_PARAMETER    Invalid parameter
 294  * @retval                  #USB_ERROR_OPERATION_FAILED     Operation failed
 295  *
 296  */
 297 int usb_accessory_request_permission(usb_accessory_h accessory, usb_accessory_permission_response_cb callback, void* user_data);
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif
 302
 303 /**
 304  * @}
 305  */
 306
 307 #endif  // __TIZEN_SYSTEM_USB_ACCESSORY_H__
 308