SAMV71 Xplained Ultra Software Package 1.4

host_hid.h

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