usbctrl.h

/*
 * If not stated otherwise in this file or this component's Licenses.txt file the
 * following copyright and licenses apply:
 *
 * Copyright 2016 RDK Management
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/
 
/**
 * @defgroup USB_CNTRL RDK Usb Device Control
 * - Supports USB detection and control functionality to enable USB detection and control from application.
 * - This ensures that the USB port works as expected before using peripherals and capabilities that use the USB port.
 *
 * @defgroup USB_CNTRL_TYPES USB Control Types
 * @ingroup  USB_CNTRL
 *
 * @defgroup USB_CNTRL_APIS USB Control APIs
 * @ingroup  USB_CNTRL
 *
 **/
 
/*
 * The following table is are published properties by this library
 */
 typedef enum {
//Device Level                    //sysfs attr
RUSBCTRL_PROPNAME_MANUFACTURER = 0,   //"manufacturer"
RUSBCTRL_PROPNAME_PRODUCT,        // "product"
RUSBCTRL_PROPNAME_MODEL,          // "idProduct"
RUSBCTRL_PROPNAME_VENDOR,         // "idVendor"
RUSBCTRL_PROPNAME_SERIAL,         //"serial"
// Interface Level
RUSBCTRL_PROPNAME_DEVTYPE,        //"bInterfaceClass"
RUSBCTRL_PROPNAME_DEVSUBTYPE,     // "bInterfaceSubClass"
} rusbCtrl_propname_t;
 
 
typedef enum {
        RUSBCTRL_SUCCESS = 0,
        RUSBCTRL_FAILURE = -1
} rusbCtrl_result_t;
 
/**
 * @addtogroup USB_CNTRL_TYPES
 * @{
 */
 
/**
 * @brief The callback will be invoked when a device of monitored type is inserted or removed.
 *
 * @param[in] devId     Device ID is a unique Id generated by libusbctrl. Device ID should be a Id that can identify
 *                      a USB interface. A USB device can have multiple interfaces.
 * @param[in] inserted  This indicates of the device is inserted or removed.
 * @param[in] cbData    Callback data.
 */
typedef void (*rusbCtrl_devCallback_t)(int devId, int inserted, void *cbData);
 
/** @} */  //END OF GROUP USB_CNTRL_TYPES
 
/**
 * @addtogroup USB_CNTRL_APIS
 * @{
 */
 
/**
 * @brief This API Initiate the library to a state that it is ready to detect device events and invoke callbacks.
 *
 * Library can be initialized multple times. But init and term must match.
 *
 * @return Returns status of the operation.
 */
int rusbCtrl_init(void);
 
/**
 * @brief This API Release all allocated resources.
 *
 * @return Returns status of the operation.
 */
int rusbCtrl_term();
 
/**
 * @brief This callback Allow application to listen for USB insert/remove events.
 * An appliction can only register 1 callback.
 * (This constraint may be lifted in the future if needed)
 *
 * @param[in] cb                Callback Function.
 * @param[in] cbData            Callback Data.
 * @param[in] devList           Device list is a pointer to an array containing list of connected devices.
 * @param[in] devListNumEntries Number of entries in the array.
 *
 * @return Returns status of the operation.
 *
 * @note
 * devList is a pointer to an array allocated on the heap and must be freed by the user.
 */
int rusbCtrl_registerCallback(rusbCtrl_devCallback_t cb, void *cbData, int **devList, int *devListNumEntries);
 
/**
 * @brief This API compares unique identifier against its internal data structures and validates to provides property value.
 * @param[in] devId             Device ID.
 * @param[in] propertyName      Set of properties published by libusbCtrl.
 *
 * @return On success returns property data. On failure returns NULL.
 *
 * @note
 * User is responsible to free() the value returned.
 */
char *rusbCtrl_getProperty(int devId, const char *propertyName);
 
/** @} */  //END OF GROUP USB_CNTRL_APIS