Wed, 05 Aug 2009 17:32:05 +0100
updated README
1 /****************************************************************************
2 * Project: P-touch printer driver library
3 * Developer: Philip Pemberton
4 * Purpose: Make Brother P-touch (PT-series) printers do something besides
5 * gather dust.
6 *
7 * Currently supports:
8 * PT-2450DX
9 ****************************************************************************/
11 #ifndef PTOUCH_H
12 #define PTOUCH_H
14 #include <gd.h>
16 /**
17 * @brief Device information structure
18 *
19 * This is used to store the state of the printer as of the last call to
20 * pt_GetStatus(), the current job settings, and other details required
21 * by the printer driver. User code should not change any parameters inside
22 * a pt_Device struct under any circumstances. For further information on
23 * the various fields, see the Brother PT-9500PC Command Reference.
24 */
25 typedef struct {
26 /// Reference to the printer device
27 FILE *fp;
28 /// Error information
29 int errorInfo[2];
30 /// Label width (in millimetres)
31 int mediaWidth;
32 /// Label type
33 int mediaType;
34 /// Label length (in millimetres)
35 int mediaLength;
36 /// Label width in pixels
37 int pixelWidth;
38 /// Printer status type
39 int statusType;
40 /// Printing phase type
41 int phaseType;
42 /// Printing phase, high byte
43 int phaseHi;
44 /// Printing phase, low byte
45 int phaseLo;
46 /// Notification number
47 int notification;
49 /// Print parameter: autocutter enable
50 int autocut;
51 /// Print parameter: mirror printing enable
52 int mirror;
53 // TODO: add support for half-cut (when I get a printer that supports it)
54 // TODO: add support for printing a separator line when autocut is off
55 } pt_Device;
57 /*
58 * Function return codes
59 */
60 enum {
61 /// Operation completed successfully
62 PT_ERR_SUCCESS = 0,
64 /// Data transfer timed out
65 PT_ERR_TIMEOUT = -1,
67 /// Invalid parameter
68 PT_ERR_BAD_PARAMETER = -2,
70 /// Label image is too large for this label tape
71 PT_ERR_LABEL_TOO_WIDE = -3,
73 /// Label has a length of zero
74 PT_ERR_LABEL_ZERO_LENGTH = -4,
76 /// Printer is not ready
77 PT_ERR_PRINTER_NOT_READY = -5
78 };
80 /*
81 * Job options
82 */
83 typedef enum {
84 /// Mirror -- mirror the printed label vertically
85 PT_OPTION_MIRROR,
86 /// Auto-cutter -- enable or disable automatic label cutting
87 PT_OPTION_AUTOCUT
88 } PT_E_OPTION;
90 /**
91 * @brief Initialise the printer.
92 *
93 * Initialises the printer and returns a pointer to a pt_Device struct
94 * describing it.
95 *
96 * @param path Path to the printer device file (e.g. /dev/usb/lp0)
97 * @return On success, a pt_Device struct referring to the printer.
98 * On failure, NULL.
99 */
100 pt_Device *pt_Initialise(char *path);
102 /**
103 * @brief Close a printer device.
104 *
105 * Closes the connection to the printer, and destroys the pt_Device struct.
106 *
107 * @param dev A pt_Device struct created by pt_Initialise.
108 */
109 void pt_Close(pt_Device *dev);
111 /**
112 * @brief Get the current status of the printer.
113 *
114 * Queries the printer for its current status, then returns the result.
115 *
116 * @param dev A pt_Device struct created by pt_Initialise.
117 * @return Any valid PT_ERR_* constant. The pt_Device struct passed in
118 * is also updated with the current status of the printer.
119 */
120 int pt_GetStatus(pt_Device *dev);
122 /**
123 * @brief Set a job option for the next print job.
124 *
125 * Sets a job option (specified by <b>option</b>) for the next print job.
126 * These options include printer features like auto-cutting and mirroring
127 * of the label image.
128 *
129 * @param dev A pt_Device struct created by pt_Initialise.
130 * @param option One of the PT_OPTION_* constants specifying the parameter
131 * that is to be set.
132 * @param value The value to assign to the job option.
133 * @return <b>PT_ERR_BAD_PARAMETER:</b> Either <b>dev</b> was equal to NULL,
134 * or the option value specified in <b>option</b> was invalid.<br>
135 * <b>PT_ERR_SUCCESS:</b> Operation completed successfully, the current value
136 * of the option parameter is now set to the contents of <b>value</b>.
137 */
138 int pt_SetOption(pt_Device *dev, PT_E_OPTION option, int value);
140 /**
141 * @brief Get the current value of a job option for the next print job.
142 *
143 * Returns the current value of a job option (specified by <b>option</b>)
144 * for the next print job.
145 * These options include printer features like auto-cutting and mirroring
146 * of the label image.
147 *
148 * @param dev A pt_Device struct created by pt_Initialise.
149 * @param option One of the PT_OPTION_* constants specifying the parameter
150 * that is to be returned.
151 * @param value A pointer to an <b>int</b> that will contain the value
152 * of the job option.
153 * @return <b>PT_ERR_BAD_PARAMETER:</b> Either <b>dev</b> or <b>value</b> was
154 * equal to NULL, or the option value specified in <b>option</b> was invalid.<br>
155 * <b>PT_ERR_SUCCESS:</b> Operation completed successfully, the current value
156 * of the option parameter is now stored in <b>value</b>.
157 */
158 int pt_GetOption(pt_Device *dev, PT_E_OPTION option, int *value);
160 /**
161 * @brief Print one or more labels.
162 *
163 * Takes a pointer to an array of Libgd images, and prints each of them.
164 *
165 * @param dev A pt_Device struct created by pt_Initialise.
166 * @param labels A pointer to an array of gdImagePtr objects containing
167 * the labels to be printed.
168 * @param count The number of labels to be printed.
169 * @return Any valid PT_ERR_* constant.
170 */
171 int pt_Print(pt_Device *dev, gdImagePtr *labels, int count);
173 #endif // PTOUCH_H