SAMV71 Xplained Ultra Software Package 1.5

host_hid.h

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 /*! \file *********************************************************************
00031  *
00032  * \brief Management of the generic host HID features.
00033  *
00034  * This file manages the generic host HID features.
00035  * \author               Atmel Corporation: http://www.atmel.com \n
00036  *                       Support and FAQ: http://support.atmel.no/
00037  *
00038  ******************************************************************************/
00039 
00040 #ifndef _HOST_HID_H_
00041 #define _HOST_HID_H_
00042 
00043 
00044 //_____ I N C L U D E S ________________________________________________________
00045 
00046 #include "compiler.h"
00047 #include "hid.h"
00048 
00049 
00050 //_____ M A C R O S ____________________________________________________________
00051 
00052 
00053 //_____ D E F I N I T I O N S __________________________________________________
00054 
00055 //! HID report descriptor item.
00056 typedef struct {
00057     U8 type;
00058     U8 tag;
00059     Bool long_format;
00060     union {
00061         hid_short_item_data_t short_data;
00062         struct {
00063             U8 size;
00064             const void *data;
00065         } long_data;
00066     };
00067 } host_hid_item_t;
00068 
00069 
00070 //_____ D E C L A R A T I O N S ________________________________________________
00071 
00072 /*! \name Standard Requests Applied to HID
00073  */
00074 //! @{
00075 
00076 /*! \brief Gets a HID class descriptor.
00077  *
00078  * \param descriptor_type Type of the descriptor to get.
00079  * \param descriptor_index Index of the descriptor to get.
00080  * \param s_interface The supported interface number of which to get the
00081  *                    descriptor.
00082  *
00083  * \return Status.
00084  */
00085 extern Status_t host_hid_get_descriptor(U8 descriptor_type, U8 descriptor_index,
00086                                         U8 s_interface);
00087 
00088 /*! \brief Sets a HID class descriptor.
00089  *
00090  * \param descriptor_type Type of the descriptor to set.
00091  * \param descriptor_index Index of the descriptor to set.
00092  * \param s_interface The supported interface number of which to set the
00093  *                    descriptor.
00094  * \param length Length of the descriptor to set.
00095  *
00096  * \return Status.
00097  */
00098 extern Status_t host_hid_set_descriptor(U8 descriptor_type, U8 descriptor_index,
00099                                         U8 s_interface, U16 length);
00100 
00101 //! @}
00102 
00103 /*! \name HID-Specific Requests
00104  */
00105 //! @{
00106 
00107 /*! \brief Gets a HID report.
00108  *
00109  * \param report_type Type of the report to get.
00110  * \param report_id ID of the report to get.
00111  * \param s_interface The supported interface number of which to get the report.
00112  *
00113  * \return Status.
00114  */
00115 extern Status_t host_hid_get_report(U8 report_type, U8 report_id,
00116                                     U8 s_interface);
00117 
00118 /*! \brief Sets a HID report.
00119  *
00120  * \param report_type Type of the report to set.
00121  * \param report_id ID of the report to set.
00122  * \param s_interface The supported interface number of which to set the report.
00123  * \param length Length of the report to set.
00124  *
00125  * \return Status.
00126  */
00127 extern Status_t host_hid_set_report(U8 report_type, U8 report_id,
00128                                     U8 s_interface, U16 length);
00129 
00130 /*! \brief Reads the current idle rate for a particular Input report.
00131  *
00132  * \param report_id ID of the report of which to get the idle rate.
00133  * \param s_interface The supported interface number of which to get the idle
00134  *                    rate.
00135  *
00136  * \return Idle duration with a 4-ms resolution, or
00137  *         \c HID_IDLE_DURATION_INDEFINITE.
00138  */
00139 extern U8 host_hid_get_idle(U8 report_id, U8 s_interface);
00140 
00141 /*! \brief Silences a particular report on the Interrupt In pipe until a new
00142  *         event occurs or the specified amount of time passes.
00143  *
00144  * \param duration_4_ms Idle duration with a 4-ms resolution, or
00145  *                      \c HID_IDLE_DURATION_INDEFINITE.
00146  * \param report_id ID of the report of which to set the idle rate (can be
00147  *                  \c HID_REPORT_ID_ALL).
00148  * \param s_interface The supported interface number of which to set the idle
00149  *                    rate.
00150  *
00151  * \return Status.
00152 */
00153 extern Status_t host_hid_set_idle(U8 duration_4_ms, U8 report_id,
00154                                   U8 s_interface);
00155 
00156 /*! \brief Reads which protocol is currently active (either the boot protocol or
00157  *         the report protocol).
00158  *
00159  * \param s_interface The supported interface number of which to get the
00160  *                    protocol.
00161  *
00162  * \return Protocol: \c HID_BOOT_PROTOCOL or \c HID_REPORT_PROTOCOL.
00163  *
00164  * \note This request is supported by devices in the Boot subclass.
00165  */
00166 extern U8 host_hid_get_protocol(U8 s_interface);
00167 
00168 /*! \brief Switches between the boot protocol and the report protocol (or vice
00169  *         versa).
00170  *
00171  * \param protocol Protocol: \c HID_BOOT_PROTOCOL or \c HID_REPORT_PROTOCOL.
00172  * \param s_interface The supported interface number of which to set the
00173  *                    protocol.
00174  *
00175  * \return Status.
00176  *
00177  * \note This request is supported by devices in the Boot subclass.
00178  *
00179  * \note When initialized, all devices default to the report protocol. However,
00180  *       the host should not make any assumptions about the device's state and
00181  *       should set the desired protocol whenever initializing a device.
00182  */
00183 extern Status_t host_hid_set_protocol(U8 protocol, U8 s_interface);
00184 
00185 //! @}
00186 
00187 /*! \name HID Report Descriptor Parsing Functions
00188  */
00189 //! @{
00190 
00191 /*! \brief Gets the next HID report descriptor item.
00192  *
00193  * \param item Pointer to the item structure to fill.
00194  *
00195  * \return Status.
00196  *
00197  * \note \ref host_hid_get_descriptor must have been called before this function
00198  *       for \c HID_DESCRIPTOR and \c HID_REPORT_DESCRIPTOR.
00199  */
00200 extern Status_bool_t host_hid_get_item(host_hid_item_t *item);
00201 
00202 //! @}
00203 
00204 
00205 #endif  // _HOST_HID_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines