Printer.h 15.1 KB
 Dean Camera committed May 08, 2010 1 2 3 /* LUFA Library Copyright (C) Dean Camera, 2010.  4   Dean Camera committed May 08, 2010 5  dean [at] fourwalledcubicle [dot] com  Dean Camera committed Oct 28, 2010 6  www.lufa-lib.org  Dean Camera committed May 08, 2010 7 8 9 10 11 */ /* Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)  12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 15  all copies and that both that the copyright notice and this  16 17 18  permission notice and warranty disclaimer appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the  Dean Camera committed May 08, 2010 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35  software without specific, written prior permission. The author disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. */ /** \file * \brief Host mode driver for the library USB Printer Class driver. * * Host mode driver for the library USB Printer Class driver. *  Dean Camera committed Oct 24, 2010 36 37  * \note This file should not be included directly. It is automatically included as needed by the USB module driver * dispatch header located in LUFA/Drivers/USB.h.  Dean Camera committed May 08, 2010 38 39 40 41 42 43 44  */ /** \ingroup Group_USBClassPrinter * @defgroup Group_USBClassPrinterHost Printer Class Host Mode Driver * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module:  Dean Camera committed Jul 19, 2010 45  * - LUFA/Drivers/USB/Class/Host/Printer.c (Makefile source module name: LUFA_SRC_USBCLASS)  Dean Camera committed May 08, 2010 46 47 48 49 50 51 52 53 54 55 56 57 58  * * \section Module Description * Host Mode USB Class driver framework interface, for the Printer USB Class driver. * * @{ */ #ifndef __PRINTER_CLASS_HOST_H__ #define __PRINTER_CLASS_HOST_H__ /* Includes: */ #include "../../USB.h" #include "../Common/Printer.h"  59   Dean Camera committed May 08, 2010 60 61 62 63 64 65 66  /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks: */ #if !defined(__INCLUDE_FROM_PRINTER_DRIVER)  Dean Camera committed Oct 24, 2010 67 68 69 70 71  #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. #endif #if defined(__INCLUDE_FROM_PRINTER_HOST_C) && defined(NO_STREAM_CALLBACKS) #error The NO_STREAM_CALLBACKS compile time option cannot be used in projects using the library Class drivers.  Dean Camera committed May 08, 2010 72 73 74 75 76 77 78 79 80 81 82 83 84 85  #endif /* Public Interface - May be used in end-application: */ /* Type Defines: */ /** \brief Printer Class Host Mode Configuration and State Structure. * * Class state structure. An instance of this structure should be made within the user application, * and passed to each of the Printer class driver functions as the PRNTInterfaceInfo parameter. This * stores each Printer interface's configuration and state information. */ typedef struct { const struct {  Dean Camera committed Jun 17, 2010 86 87  uint8_t DataINPipeNumber; /**< Pipe number of the Printer interface's IN data pipe. */ bool DataINPipeDoubleBank; /**< Indicates if the Printer interface's IN data pipe should use double banking. */  Dean Camera committed May 08, 2010 88   Dean Camera committed Jun 17, 2010 89 90  uint8_t DataOUTPipeNumber; /**< Pipe number of the Printer interface's OUT data pipe. */ bool DataOUTPipeDoubleBank; /**< Indicates if the Printer interface's OUT data pipe should use double banking. */  Dean Camera committed May 08, 2010 91 92 93 94 95 96 97  } Config; /**< Config data for the USB class interface within the device. All elements in this section * must be set or the interface will fail to enumerate and operate correctly. */ struct { bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid * after \ref PRNT_Host_ConfigurePipes() is called and the Host state machine is in the  Dean Camera committed Jun 17, 2010 98  * Configured state.  Dean Camera committed May 08, 2010 99  */  Dean Camera committed Jun 17, 2010 100 101  uint8_t InterfaceNumber; /**< Interface index of the Printer interface within the attached device. */ uint8_t AlternateSetting; /**< Alternate setting within the Printer Interface in the attached device. */  Dean Camera committed May 08, 2010 102   Dean Camera committed Jun 17, 2010 103 104  uint16_t DataINPipeSize; /**< Size in bytes of the Printer interface's IN data pipe. */ uint16_t DataOUTPipeSize; /**< Size in bytes of the Printer interface's OUT data pipe. */  Dean Camera committed May 08, 2010 105 106 107 108 109 110 111  } State; /**< State data for the USB class interface within the device. All elements in this section * may be set to initial values, but may also be ignored to default to sane values when * the interface is enumerated. */ } USB_ClassInfo_PRNT_Host_t; /* Enums: */  Dean Camera committed Sep 28, 2010 112  enum PRNT_Host_EnumerationFailure_ErrorCodes_t  Dean Camera committed May 08, 2010 113  {  Dean Camera committed Jun 17, 2010 114 115  PRNT_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */ PRNT_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */  Dean Camera committed Sep 30, 2010 116  PRNT_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Printer interface was not found in the device's Configuration Descriptor. */  Dean Camera committed Dec 02, 2010 117  PRNT_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */  Dean Camera committed May 08, 2010 118  };  119   Dean Camera committed May 08, 2010 120  /* Function Prototypes: */  121 122 123 124 125 126 127 128  /** General management task for a given Printer host class interface, required for the correct operation of * the interface. This should be called frequently in the main program loop, before the master USB management task * \ref USB_USBTask(). * * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. */ void PRNT_Host_USBTask(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed May 08, 2010 129 130 131 132 133 134  /** Host interface configuration routine, to configure a given Printer host interface instance using the * Configuration Descriptor read from an attached USB device. This function automatically updates the given Printer * instance's state values and configures the pipes required to communicate with the interface if it is found within * the device. This should be called once after the stack has enumerated the attached device, while the host state * machine is in the Addressed state. *  Dean Camera committed Sep 30, 2010 135 136 137 138  * \note The pipe index numbers as given in the interface's configuration structure must not overlap with any other * interface, or pipe bank corruption will occur. Gaps in the allocated pipe numbers or non-sequential indexes * within a single interface is allowed, but no two interfaces of any type have have interleaved pipe indexes. *  Dean Camera committed Jun 17, 2010 139 140 141  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor. * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor.  Dean Camera committed May 08, 2010 142  *  Dean Camera committed Sep 28, 2010 143  * \return A value from the \ref PRNT_Host_EnumerationFailure_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 144  */  Dean Camera committed Jul 21, 2010 145 146  uint8_t PRNT_Host_ConfigurePipes(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo, uint16_t ConfigDescriptorSize,  Dean Camera committed May 08, 2010 147  void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);  148   Dean Camera committed May 08, 2010 149 150 151  /** Configures the printer to enable Bidirectional mode, if it is not already in this mode. This should be called * once the connected device's configuration has been set, to ensure the printer is ready to accept commands. *  Dean Camera committed Jun 17, 2010 152  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state.  Dean Camera committed May 08, 2010 153  *  Dean Camera committed Jun 17, 2010 154  * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.  Dean Camera committed May 08, 2010 155 156  */ uint8_t PRNT_Host_SetBidirectionalMode(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  157   Dean Camera committed May 08, 2010 158 159 160  /** Retrieves the status of the virtual Printer port's inbound status lines. The result can then be masked against the * PRNT_PORTSTATUS_* macros to determine the printer port's status. *  Dean Camera committed Jun 17, 2010 161 162  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * \param[out] PortStatus Location where the retrieved port status should be stored.  Dean Camera committed May 08, 2010 163  *  Dean Camera committed Jun 17, 2010 164  * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.  Dean Camera committed May 08, 2010 165  */  Dean Camera committed Jul 21, 2010 166 167  uint8_t PRNT_Host_GetPortStatus(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo, uint8_t* const PortStatus)  Dean Camera committed May 08, 2010 168 169 170 171  ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /** Soft-resets the attached printer, readying it for new commands. *  Dean Camera committed Jun 17, 2010 172  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state.  Dean Camera committed May 08, 2010 173  *  Dean Camera committed Jun 17, 2010 174  * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.  Dean Camera committed May 08, 2010 175 176 177  */ uint8_t PRNT_Host_SoftReset(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  178 179  /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared. *  Dean Camera committed Oct 12, 2010 180  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  181 182 183 184 185 186 187 188  * call will fail. * * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * * \return A value from the \ref Pipe_WaitUntilReady_ErrorCodes_t enum. */ uint8_t PRNT_Host_Flush(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed May 08, 2010 189 190 191 192  /** Sends the given raw data stream to the attached printer's input endpoint. This should contain commands that the * printer is able to understand - for example, PCL data. Not all printers accept all printer languages; see * \ref PRNT_Host_GetDeviceID() for details on determining acceptable languages for an attached printer. *  Dean Camera committed Oct 12, 2010 193  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  Dean Camera committed Jun 15, 2010 194  * call will fail.  Dean Camera committed May 08, 2010 195  *  Dean Camera committed Jun 17, 2010 196  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state.  Dean Camera committed Sep 07, 2010 197 198  * \param[in] Buffer Pointer to a buffer containing the raw command stream to send to the printer. * \param[in] Length Size in bytes of the command stream to be sent.  Dean Camera committed May 08, 2010 199  *  Dean Camera committed Jun 17, 2010 200  * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 201  */  Dean Camera committed Sep 07, 2010 202  uint8_t PRNT_Host_SendString(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo,  203  void* Buffer,  Dean Camera committed Sep 07, 2010 204  const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);  Dean Camera committed May 08, 2010 205   206 207  /** Sends a given byte to the attached USB device, if connected. If a device is not connected when the function is called, the * byte is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the  208  * \ref PRNT_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be  209 210  * packed into a single pipe packet, increasing data throughput. *  Dean Camera committed Oct 12, 2010 211  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  212 213 214 215 216 217 218 219 220 221  * call will fail. * * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * \param[in] Data Byte of data to send to the device. * * \return A value from the \ref Pipe_WaitUntilReady_ErrorCodes_t enum. */ uint8_t PRNT_Host_SendByte(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo, const uint8_t Data) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed Sep 07, 2010 222 223 224 225 226  /** Determines the number of bytes received by the printer interface from the device, waiting to be read. This indicates the number * of bytes in the IN pipe bank only, and thus the number of calls to \ref PRNT_Host_ReceiveByte() which are guaranteed to succeed * immediately. If multiple bytes are to be received, they should be buffered by the user application, as the pipe bank will not be * released back to the USB controller until all bytes are read. *  Dean Camera committed Oct 12, 2010 227  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  Dean Camera committed Sep 07, 2010 228 229 230 231 232 233  * call will fail. * * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * * \return Total number of buffered bytes received from the device. */  234 235  uint16_t PRNT_Host_BytesReceived(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo);  Dean Camera committed Sep 07, 2010 236 237 238 239  /** 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 * returns a negative value. The \ref PRNT_Host_BytesReceived() function may be queried in advance to determine how many bytes * are currently buffered in the Printer interface's data receive pipe. *  Dean Camera committed Oct 12, 2010 240  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  Dean Camera committed Sep 07, 2010 241 242 243 244 245 246 247  * call will fail. * * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * * \return Next received byte from the device, or a negative value if no data received. */ int16_t PRNT_Host_ReceiveByte(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo);  248   Dean Camera committed May 08, 2010 249 250 251 252 253 254 255  /** Retrieves the attached printer device's ID string, formatted according to IEEE 1284. This string is sent as a * Unicode string from the device and is automatically converted to an ASCII encoded C string by this function, thus * the maximum reportable string length is two less than the size given (to accommodate the Unicode string length * bytes which are removed). * * This string, when supported, contains the model, manufacturer and acceptable printer languages for the attached device. *  Dean Camera committed Jun 17, 2010 256 257 258  * \param[in,out] PRNTInterfaceInfo Pointer to a structure containing a Printer Class host configuration and state. * \param[out] DeviceIDString Pointer to a buffer where the Device ID string should be stored, in ASCII format. * \param[in] BufferSize Size in bytes of the buffer allocated for the Device ID string.  Dean Camera committed May 08, 2010 259  *  Dean Camera committed Jun 17, 2010 260  * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 261  */  Dean Camera committed Jul 21, 2010 262 263  uint8_t PRNT_Host_GetDeviceID(USB_ClassInfo_PRNT_Host_t* const PRNTInterfaceInfo, char* const DeviceIDString,  264  const uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);  Dean Camera committed May 08, 2010 265 266 267 268  /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Function Prototypes: */  Dean Camera committed Oct 24, 2010 269  #if defined(__INCLUDE_FROM_PRINTER_HOST_C)  270 271  static uint8_t DCOMP_PRNT_Host_NextPRNTInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1); static uint8_t DCOMP_PRNT_Host_NextPRNTInterfaceEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed May 08, 2010 272 273  #endif #endif  274   Dean Camera committed May 08, 2010 275 276 277 278 279 280 281 282  /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif #endif /** @} */  283