events.h

LUFA (Lightweight USB Framework for AVRs) is my first foray into the world of USB. Originally based

			 */
			void USB_UIDChange(void);

			/** Event for USB host error. This event fires when a hardware fault has occurred whilst the USB
			 *  interface is in host mode.
			 *
			 *  \param ErrorCode  Error code indicating the failure reason, a value in \ref USB_Host_ErrorCodes_t
			 *                    located in Host.h.
			 *
			 *  \note This event only exists on USB AVR models which supports host mode.
			 *
			 *  \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 */
			void USB_HostError(const uint8_t ErrorCode);
			
			/** Event for USB device attachment. This event fires when a the USB interface is in host mode, and
			 *  a USB device has been connected to the USB interface. This is interrupt driven, thus fires before
			 *  the standard \ref USB_Connect event and so can be used to programmatically start the USB management
			 *  task to reduce CPU consumption.
			 *
			 *  \note This event only exists on USB AVR models which supports host mode.
			 *
			 *  \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 *
			 *  \see \ref TASK(USB_USBTask) for more information on the USB management task and reducing CPU usage.
			 */
			void USB_DeviceAttached(void);

			/** Event for USB device removal. This event fires when a the USB interface is in host mode, and
			 *  a USB device has been removed the USB interface whether or not it has been enumerated. This
			 *  can be used to programmatically stop the USB management task to reduce CPU consumption.
			 *
			 *  \note This event only exists on USB AVR models which supports host mode.
			 *
			 *  \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 *
			 *  \see \ref TASK(USB_USBTask) for more information on the USB management task and reducing CPU usage.
			 */
			void USB_DeviceUnattached(void);
			
			/** Event for USB device enumeration failure. This event fires when a the USB interface is
			 *  in host mode, and an attached USB device has failed to enumerate completely.
			 *
			 *  \param ErrorCode  Error code indicating the failure reason, a value in 
			 *                    \ref USB_Host_EnumerationErrorCodes_t located in Host.h.
			 *
			 *  \param SubErrorCode  Sub error code indicating the reason for failure - for example, if the
			 *                       ErrorCode parameter indicates a control error, this will give the error
			 *                       code returned by the \ref USB_Host_SendControlRequest() function.
			 *
			 *  \note This event only exists on USB AVR models which supports host mode.
			 *
			 *  \note This event does not exist if the USB_DEVICE_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 */
			void USB_DeviceEnumerationFailed(const uint8_t ErrorCode, const uint8_t SubErrorCode);

			/** Event for USB device enumeration completion. This event fires when a the USB interface is
			 *  in host mode and an attached USB device has been completely enumerated and is ready to be
			 *  controlled by the user application, or when the library is in device mode, and the Host
			 *  has finished enumerating the device.
			 */
			void USB_DeviceEnumerationComplete(void);

			/** Event for unhandled control requests. This event fires when a the USB host issues a control
			 *  request to the control endpoint (address 0) that the library does not handle. This may either
			 *  be a standard request that the library has no handler code for, or a class specific request
			 *  issued to the device which must be handled appropriately. Due to the strict timing requirements
			 *  on control transfers, interrupts are disabled during control request processing.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 *
			 *  \note Requests should be handled in the same manner as described in the USB 2.0 Specification,
			 *        or appropriate class specification. In all instances, the library has already read the
			 *        request SETUP parameters into the \ref USB_ControlRequest structure which should then be used
			 *        by the application to determine how to handle the issued request.
			 */
			void USB_UnhandledControlPacket(void);

			/** Event for USB configuration number changed. This event fires when a the USB host changes the
			 *  selected configuration number while in device mode. This event should be hooked in device
			 *  applications to create the endpoints and configure the device for the selected configuration.
			 *
			 *  This event fires after the value of \ref USB_ConfigurationNumber has been changed.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 */
			void USB_ConfigurationChanged(void);

			/** Event for USB suspend. This event fires when a the USB host suspends the device by halting its
			 *  transmission of Start Of Frame pulses to the device. This is generally hooked in order to move
			 *  the device over to a low power state until the host wakes up the device.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 *
			 *  \see \ref USB_WakeUp() event for accompanying Wake Up event.
			 */
			void USB_Suspend(void);

			/** Event for USB wake up. This event fires when a the USB interface is suspended while in device
			 *  mode, and the host wakes up the device by supplying Start Of Frame pulses. This is generally
			 *  hooked to pull the user application out of a lowe power state and back into normal operating
			 *  mode.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 *
			 *  \see \ref USB_Suspend() event for accompanying Suspend event.
			 */
			void USB_WakeUp(void);

			/** Event for USB interface reset. This event fires when a the USB interface is in device mode, and
			 *  a the USB host requests that the device reset its interface. This is generally hooked so that
			 *  the USB control endpoint can be switched to interrupt driven mode, by selecting it and calling
			 *  USB_INT_Enable(ENDPOINT_INT_SETUP). Before this event fires, all device endpoints are reset and
			 *  disabled.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 */
			void USB_Reset(void);
			
			/** Event for USB device mode error. This event fires when the USB interface is in device mode,
			 *  and an error occurs which prevents it from operating normally.
			 *
			 *  \param ErrorCode  Error code indicating the source of the error. One of the values in the
			 *                    \ref USB_Device_ErrorCodes_t enum located in Device.h.
			 *
			 *  \note This event does not exist if the USB_HOST_ONLY token is supplied to the compiler (see
			 *        \ref Group_USBManagement documentation).
			 */
			void USB_DeviceError(const uint8_t ErrorCode);
		#endif
		
	/* Private Interface - For use in library only: */
	#if !defined(__DOXYGEN__)
		/* Macros: */
			#define ALIAS_STUB(e)                       EVENT_HANDLER(e) ATTR_WEAK ATTR_ALIAS(USB_Event_Stub)
		
			#if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
				#define USB_VBUSChange_P                (void)
				#define USB_VBUSConnect_P               (void)
				#define USB_VBUSDisconnect_P            (void)
			#endif
			
			#define USB_Connect_P                       (void)
			#define USB_Disconnect_P                    (void)
			#define USB_DeviceEnumerationComplete_P     (void)
			
			#if defined(USB_CAN_BE_BOTH)
				#define USB_InitFailure_P               (const uint8_t ErrorCode)
				#define USB_UIDChange_P                 (void)
			#endif

			#if defined(USB_CAN_BE_HOST)
				#define USB_HostError_P                 (const uint8_t ErrorCode)
				#define USB_DeviceAttached_P            (void)
				#define USB_DeviceUnattached_P          (void)
				#define USB_DeviceEnumerationFailed_P   (const uint8_t ErrorCode, const uint8_t SubErrorCode)
			#endif
			
			#if defined(USB_CAN_BE_DEVICE)
				#define USB_UnhandledControlPacket_P    (void)
				#define USB_ConfigurationChanged_P      (void)
				#define USB_Suspend_P                   (void)
				#define USB_WakeUp_P                    (void)
				#define USB_Reset_P                     (void)
				#define USB_DeviceError_P               (const uint8_t ErrorCode)
			#endif

		/* Function Prototypes: */
			#if defined(INCLUDE_FROM_EVENTS_C)
				void USB_Event_Stub (void) ATTR_CONST;

				#if defined(USB_FULL_CONTROLLER) || defined(USB_MODIFIED_FULL_CONTROLLER)
					ALIAS_STUB(USB_VBUSChange);
					ALIAS_STUB(USB_VBUSConnect);
					ALIAS_STUB(USB_VBUSDisconnect);
				#endif
				
				ALIAS_STUB(USB_Connect);
				ALIAS_STUB(USB_Disconnect);
				ALIAS_STUB(USB_DeviceEnumerationComplete);
				
				#if defined(USB_CAN_BE_BOTH)
					ALIAS_STUB(USB_InitFailure);
					ALIAS_STUB(USB_UIDChange);
				#endif
				
				#if defined(USB_CAN_BE_HOST)
					ALIAS_STUB(USB_HostError);
					ALIAS_STUB(USB_DeviceAttached);
					ALIAS_STUB(USB_DeviceUnattached);
					ALIAS_STUB(USB_DeviceEnumerationFailed);
				#endif

				#if defined(USB_CAN_BE_DEVICE)
					ALIAS_STUB(USB_UnhandledControlPacket);
					ALIAS_STUB(USB_ConfigurationChanged);
					ALIAS_STUB(USB_Suspend);
					ALIAS_STUB(USB_WakeUp);
					ALIAS_STUB(USB_Reset);
					ALIAS_STUB(USB_DeviceError);
				#endif
			#endif
	#endif

	/* Disable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			}
		#endif
	
#endif

/** @} */