2 * @brief Host mode driver for the library USB Printer Class driver
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\r
10 * Software that is described herein is for illustrative purposes only
\r
11 * which provides customers with programming information regarding the
\r
12 * LPC products. This software is supplied "AS IS" without any warranties of
\r
13 * any kind, and NXP Semiconductors and its licensor disclaim any and
\r
14 * all warranties, express or implied, including all implied warranties of
\r
15 * merchantability, fitness for a particular purpose and non-infringement of
\r
16 * intellectual property rights. NXP Semiconductors assumes no responsibility
\r
17 * or liability for the use of the software, conveys no license or rights under any
\r
18 * patent, copyright, mask work right, or any other intellectual property rights in
\r
19 * or to any products. NXP Semiconductors reserves the right to make changes
\r
20 * in the software without notification. NXP Semiconductors also makes no
\r
21 * representation or warranty that such application will be suitable for the
\r
22 * specified use without further testing or modification.
\r
25 * Permission to use, copy, modify, and distribute this software and its
\r
26 * documentation is hereby granted, under NXP Semiconductors' and its
\r
27 * licensor's relevant copyrights in the software, without fee, provided that it
\r
28 * is used in conjunction with NXP Semiconductors microcontrollers. This
\r
29 * copyright, permission, and disclaimer notice must appear in all copies of
\r
33 /** @ingroup Group_USBClassPrinter
\r
34 * @defgroup Group_USBClassPrinterHost Printer Class Host Mode Driver
\r
36 * @section Sec_Dependencies Module Source Dependencies
\r
37 * The following files must be built with any user project that uses this module:
\r
38 * - LPCUSBlib/Drivers/USB/Class/Host/Printer.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>
\r
40 * @section Sec_ModDescription Module Description
\r
41 * Host Mode USB Class driver framework interface, for the Printer USB Class driver.
\r
46 #ifndef __PRINTER_CLASS_HOST_H__
\r
47 #define __PRINTER_CLASS_HOST_H__
\r
50 #include "../../USB.h"
\r
51 #include "../Common/PrinterClassCommon.h"
\r
53 /* Enable C linkage for C++ Compilers: */
\r
54 #if defined(__cplusplus)
\r
58 /* Preprocessor Checks: */
\r
59 #if !defined(__INCLUDE_FROM_PRINTER_DRIVER)
\r
60 #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.
\r
63 /* Public Interface - May be used in end-application: */
\r
65 /** @brief Printer Class Host Mode Configuration and State Structure.
\r
67 * Class state structure. An instance of this structure should be made within the user application,
\r
68 * and passed to each of the Printer class driver functions as the \c PRNTInterfaceInfo parameter. This
\r
69 * stores each Printer interface's configuration and state information.
\r
75 uint8_t DataINPipeNumber; /**< Pipe number of the Printer interface's IN data pipe. */
\r
76 bool DataINPipeDoubleBank; /**< Indicates if the Printer interface's IN data pipe should use double banking. */
\r
78 uint8_t DataOUTPipeNumber; /**< Pipe number of the Printer interface's OUT data pipe. */
\r
79 bool DataOUTPipeDoubleBank; /**< Indicates if the Printer interface's OUT data pipe should use double banking. */
\r
80 uint8_t PortNumber; /**< Port number that this interface is running.
\r
82 } Config; /**< Config data for the USB class interface within the device. All elements in this section
\r
83 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
\r
87 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
\r
88 * after @ref PRNT_Host_ConfigurePipes() is called and the Host state machine is in the
\r
91 uint8_t InterfaceNumber; /**< Interface index of the Printer interface within the attached device. */
\r
92 uint8_t AlternateSetting; /**< Alternate setting within the Printer Interface in the attached device. */
\r
94 uint16_t DataINPipeSize; /**< Size in bytes of the Printer interface's IN data pipe. */
\r
95 uint16_t DataOUTPipeSize; /**< Size in bytes of the Printer interface's OUT data pipe. */
\r
96 } State; /**< State data for the USB class interface within the device. All elements in this section
\r
97 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
\r
98 * the interface is enumerated.
\r
100 } USB_ClassInfo_PRNT_Host_t;
\r
103 enum PRNT_Host_EnumerationFailure_ErrorCodes_t
\r
105 PRNT_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */
\r
106 PRNT_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */
\r
107 PRNT_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Printer interface was not found in the device's Configuration Descriptor. */
\r
108 PRNT_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
\r
111 /* Function Prototypes: */
\r
112 /** @brief Host interface configuration routine, to configure a given Printer host interface instance using the
\r
113 * Configuration Descriptor read from an attached USB device. This function automatically updates the given Printer
\r
114 * instance's state values and configures the pipes required to communicate with the interface if it is found within
\r
115 * the device. This should be called once after the stack has enumerated the attached device, while the host state
\r
116 * machine is in the Addressed state.
\r
118 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
119 * @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.
\r
120 * @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.
\r
122 * @return A value from the @ref PRNT_Host_EnumerationFailure_ErrorCodes_t enum.
\r
124 uint8_t PRNT_Host_ConfigurePipes(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
125 uint16_t ConfigDescriptorSize,
\r
126 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
128 /** @brief General management task for a given Printer host class interface, required for the correct operation of
\r
129 * the interface. This should be called frequently in the main program loop, before the master USB management task
\r
130 * @ref USB_USBTask().
\r
132 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
135 void PRNT_Host_USBTask(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
137 /** @brief Configures the printer to enable Bidirectional mode, if it is not already in this mode. This should be called
\r
138 * once the connected device's configuration has been set, to ensure the printer is ready to accept commands.
\r
140 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
142 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
144 uint8_t PRNT_Host_SetBidirectionalMode(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
146 /** @brief Retrieves the status of the virtual Printer port's inbound status lines. The result can then be masked against the
\r
147 * \c PRNT_PORTSTATUS_* macros to determine the printer port's status.
\r
149 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
150 * @param PortStatus : Location where the retrieved port status should be stored.
\r
152 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
154 uint8_t PRNT_Host_GetPortStatus(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
155 uint8_t* const PortStatus)
\r
156 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
158 /** @brief Soft-resets the attached printer, readying it for new commands.
\r
160 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
162 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
164 uint8_t PRNT_Host_SoftReset(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
166 /** @brief Flushes any data waiting to be sent, ensuring that the send buffer is cleared.
\r
168 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
171 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
173 * @return A value from the @ref Pipe_WaitUntilReady_ErrorCodes_t enum.
\r
175 uint8_t PRNT_Host_Flush(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
177 /** @brief Sends the given null terminated string to the attached printer's input endpoint.
\r
179 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
182 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
183 * @param String : Pointer to a null terminated string to send.
\r
185 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
187 uint8_t PRNT_Host_SendString(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
188 void* String) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
190 /** @brief Sends the given raw data stream to the attached printer's input endpoint. This should contain commands that the
\r
191 * printer is able to understand - for example, PCL data. Not all printers accept all printer languages; see
\r
192 * @ref PRNT_Host_GetDeviceID() for details on determining acceptable languages for an attached printer.
\r
194 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
197 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
198 * @param Buffer : Pointer to a buffer containing the raw command stream to send to the printer.
\r
199 * @param Length : Size in bytes of the command stream to be sent.
\r
201 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
203 uint8_t PRNT_Host_SendData(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
205 const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
207 /** @brief Sends a given byte to the attached USB device, if connected. If a device is not connected when the function is called, the
\r
208 * byte is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the
\r
209 * @ref PRNT_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be
\r
210 * packed into a single pipe packet, increasing data throughput.
\r
212 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
215 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
216 * @param Data : Byte of data to send to the device.
\r
218 * @return A value from the @ref Pipe_WaitUntilReady_ErrorCodes_t enum.
\r
220 uint8_t PRNT_Host_SendByte(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
221 const uint8_t Data) ATTR_NON_NULL_PTR_ARG(1);
\r
223 /** @brief Determines the number of bytes received by the printer interface from the device, waiting to be read. This indicates the number
\r
224 * of bytes in the IN pipe bank only, and thus the number of calls to @ref PRNT_Host_ReceiveByte() which are guaranteed to succeed
\r
225 * immediately. If multiple bytes are to be received, they should be buffered by the user application, as the pipe bank will not be
\r
226 * released back to the USB controller until all bytes are read.
\r
228 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
231 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
233 * @return Total number of buffered bytes received from the device.
\r
235 uint16_t PRNT_Host_BytesReceived(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo);
\r
237 /** @brief Reads a byte of data from the device. If no data is waiting to be read of if a USB device is not connected, the function
\r
238 * returns a negative value. The @ref PRNT_Host_BytesReceived() function may be queried in advance to determine how many bytes
\r
239 * are currently buffered in the Printer interface's data receive pipe.
\r
241 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
244 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
246 * @return Next received byte from the device, or a negative value if no data received.
\r
248 int16_t PRNT_Host_ReceiveByte(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo);
\r
250 /** @brief Retrieves the attached printer device's ID string, formatted according to IEEE 1284. This string is sent as a
\r
251 * Unicode string from the device and is automatically converted to an ASCII encoded C string by this function, thus
\r
252 * the maximum reportable string length is two less than the size given (to accommodate the Unicode string length
\r
253 * bytes which are removed).
\r
255 * This string, when supported, contains the model, manufacturer and acceptable printer languages for the attached device.
\r
257 * @param PRNTInterfaceInfo : Pointer to a structure containing a Printer Class host configuration and state.
\r
258 * @param DeviceIDString : Pointer to a buffer where the Device ID string should be stored, in ASCII format.
\r
259 * @param BufferSize : Size in bytes of the buffer allocated for the Device ID string.
\r
261 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
263 uint8_t PRNT_Host_GetDeviceID(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,
\r
264 char* const DeviceIDString,
\r
265 const uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
267 /* Private Interface - For use in library only: */
\r
268 #if !defined(__DOXYGEN__)
\r
269 /* Function Prototypes: */
\r
270 #if defined(__INCLUDE_FROM_PRINTER_HOST_C)
\r
271 static uint8_t DCOMP_PRNT_Host_NextPRNTInterface(void* const CurrentDescriptor)
\r
272 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
273 static uint8_t DCOMP_PRNT_Host_NextPRNTInterfaceEndpoint(void* const CurrentDescriptor)
\r
274 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
278 /* Disable C linkage for C++ Compilers: */
\r
279 #if defined(__cplusplus)
\r
projects / freertos / blob