include/usb_accessory.h

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