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