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_