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_