xref: /titanic_41/usr/src/lib/print/libpapi-common/common/papi.h (revision a18dc42fc967d11feba9b8be61c6727dc6c56b48)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  *
26  */
27 
28 #ifndef _PAPI_H
29 #define	_PAPI_H
30 
31 /* $Id: papi.h 161 2006-05-03 04:32:59Z njacobs $ */
32 
33 #pragma ident	"%Z%%M%	%I%	%E% SMI"
34 
35 #include <sys/types.h>
36 #include <time.h>
37 #include <stdio.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /*
44  * Types
45  */
46 
47 /*	service related types	*/
48 typedef void *papi_service_t;
49 typedef void *papi_printer_t;
50 typedef void *papi_job_t;
51 typedef void *papi_stream_t;
52 
53 typedef enum {
54 	PAPI_ENCRYPT_IF_REQUESTED,	/* Encrypt if requested (TLS upgrade) */
55 	PAPI_ENCRYPT_NEVER,		/* Never encrypt */
56 	PAPI_ENCRYPT_REQUIRED,		/* Encryption required (TLS upgrade) */
57 	PAPI_ENCRYPT_ALWAYS		/* Always encrypt (SSL) */
58 } papi_encryption_t;
59 
60 /*	attribute related types	*/
61 typedef enum {
62 	PAPI_STRING,
63 	PAPI_INTEGER,
64 	PAPI_BOOLEAN,
65 	PAPI_RANGE,
66 	PAPI_RESOLUTION,
67 	PAPI_DATETIME,
68 	PAPI_COLLECTION,
69 	PAPI_METADATA
70 } papi_attribute_value_type_t;
71 
72 typedef enum {
73 	PAPI_RES_PER_INCH = 3,
74 	PAPI_RES_PER_CM
75 } papi_resolution_unit_t;
76 
77 enum {	/* for boolean values */
78 	PAPI_FALSE = 0,
79 	PAPI_TRUE = 1
80 };
81 
82 typedef enum {
83 	PAPI_UNSUPPORTED = 0x10,
84 	PAPI_DEFAULT = 0x11,
85 	PAPI_UNKNOWN,
86 	PAPI_NO_VALUE,
87 	PAPI_NOT_SETTABLE = 0x15,
88 	PAPI_DELETE = 0x16
89 } papi_metadata_t;
90 
91 #define	PAPI_LIST_JOBS_OTHERS		0x0001
92 #define	PAPI_LIST_JOBS_COMPLETED	0x0002
93 #define	PAPI_LIST_JOBS_NOT_COMPLETED	0x0004
94 #define	PAPI_LIST_JOBS_ALL		0xFFFF
95 
96 typedef struct papi_attribute_s papi_attribute_t;
97 
98 typedef union {
99 	char *string;				/* PAPI_STRING value */
100 	int integer;				/* PAPI_INTEGER value */
101 	char boolean;				/* PAPI_BOOLEAN value */
102 	struct {				/* PAPI_RANGE value */
103 		int lower;
104 		int upper;
105 	} range;
106 	struct {				/* PAPI_RESOLUTION value */
107 		int xres;
108 		int yres;
109 		papi_resolution_unit_t units;
110 	} resolution;
111 	time_t datetime;			/* PAPI_DATETIME value */
112 	papi_attribute_t **collection;		/* PAPI_COLLECTION value */
113 	papi_metadata_t metadata;		/* PAPI_METADATA value */
114 } papi_attribute_value_t;
115 
116 struct papi_attribute_s {
117 	char *name;				/* attribute name */
118 	papi_attribute_value_type_t type;	/* type of values */
119 	papi_attribute_value_t **values;	/* list of values */
120 };
121 
122 #define	PAPI_ATTR_APPEND	0x0001	/* Add values to attr */
123 #define	PAPI_ATTR_REPLACE	0x0002	/* Delete existing values, then add */
124 #define	PAPI_ATTR_EXCL		0x0004	/* Fail if attr exists */
125 
126 /*	job related types	*/
127 typedef enum {
128 	PAPI_JT_FORMAT_JDF = 0,
129 	PAPI_JT_FORMAT_PWG = 1
130 } papi_jt_format_t;
131 
132 typedef struct {
133 	papi_jt_format_t format;
134 	char *ticket_data;
135 	char *file_name;
136 } papi_job_ticket_t;
137 
138 /*	status related types	*/
139 typedef enum {
140 	PAPI_OK = 0x0000,
141 	PAPI_OK_SUBST,
142 	PAPI_OK_CONFLICT,
143 	PAPI_OK_IGNORED_SUBSCRIPTIONS,
144 	PAPI_OK_IGNORED_NOTIFICATIONS,
145 	PAPI_OK_TOO_MANY_EVENTS,
146 	PAPI_OK_BUT_CANCEL_SUBSCRIPTION,
147 	PAPI_REDIRECTION_OTHER_SITE = 0x0300,
148 	PAPI_BAD_REQUEST = 0x0400,
149 	PAPI_FORBIDDEN,
150 	PAPI_NOT_AUTHENTICATED,
151 	PAPI_NOT_AUTHORIZED,
152 	PAPI_NOT_POSSIBLE,
153 	PAPI_TIMEOUT,
154 	PAPI_NOT_FOUND,
155 	PAPI_GONE,
156 	PAPI_REQUEST_ENTITY,
157 	PAPI_REQUEST_VALUE,
158 	PAPI_DOCUMENT_FORMAT,
159 	PAPI_ATTRIBUTES,
160 	PAPI_URI_SCHEME,
161 	PAPI_CHARSET,
162 	PAPI_CONFLICT,
163 	PAPI_COMPRESSION_NOT_SUPPORTED,
164 	PAPI_COMPRESSION_ERROR,
165 	PAPI_DOCUMENT_FORMAT_ERROR,
166 	PAPI_DOCUMENT_ACCESS_ERROR,
167 	PAPI_ATTRIBUTES_NOT_SETTABLE,
168 	PAPI_IGNORED_ALL_SUBSCRIPTIONS,
169 	PAPI_TOO_MANY_SUBSCRIPTIONS,
170 	PAPI_IGNORED_ALL_NOTIFICATIONS,
171 	PAPI_PRINT_SUPPORT_FILE_NOT_FOUND,
172 	PAPI_INTERNAL_ERROR = 0x0500,
173 	PAPI_OPERATION_NOT_SUPPORTED,
174 	PAPI_SERVICE_UNAVAILABLE,
175 	PAPI_VERSION_NOT_SUPPORTED,
176 	PAPI_DEVICE_ERROR,
177 	PAPI_TEMPORARY_ERROR,
178 	PAPI_NOT_ACCEPTING,
179 	PAPI_PRINTER_BUSY,
180 	PAPI_ERROR_JOB_CANCELLED,
181 	PAPI_MULTIPLE_JOBS_NOT_SUPPORTED,
182 	PAPI_PRINTER_IS_DEACTIVATED,
183 	PAPI_BAD_ARGUMENT,
184 	PAPI_JOB_TICKET_NOT_SUPPORTED
185 } papi_status_t;
186 
187 /*	list filter related	*/
188 typedef enum {
189 	PAPI_FILTER_BITMASK = 0
190 } papi_filter_type_t;
191 
192 typedef struct {
193 	papi_filter_type_t type;
194 	union {
195 		struct {			/* PAPI_FILTER_BITMASK */
196 			unsigned int mask;
197 			unsigned int value;
198 		} bitmask;
199 	} filter;
200 } papi_filter_t;
201 
202 enum {
203 	PAPI_PRINTER_LOCAL = 0x0000,	/* Local destination */
204 	PAPI_PRINTER_CLASS = 0x0001,	/* Printer class */
205 	PAPI_PRINTER_REMOTE = 0x0002,	/* Remote destination */
206 	PAPI_PRINTER_BW = 0x0004,	/* Can do B&W printing */
207 	PAPI_PRINTER_COLOR = 0x0008,	/* Can do color printing */
208 	PAPI_PRINTER_DUPLEX = 0x0010,	/* Can do duplex printing */
209 	PAPI_PRINTER_STAPLE = 0x0020,	/* Can do stapling */
210 	PAPI_PRINTER_COPIES = 0x0040,	/* Can do copies */
211 	PAPI_PRINTER_COLLATE = 0x0080,	/* Can collate copies */
212 	PAPI_PRINTER_PUNCH = 0x0100,	/* Can punch output */
213 	PAPI_PRINTER_COVER = 0x0200,	/* Can cover output */
214 	PAPI_PRINTER_BIND = 0x0400,	/* Can bind output */
215 	PAPI_PRINTER_SORT = 0x0800,	/* Can sort output */
216 	PAPI_PRINTER_SMALL = 0x1000,	/* Can do letter/legal/a4 */
217 	PAPI_PRINTER_MEDIUM = 0x2000,	/* Can do tabloid/B/C/A3/A2 */
218 	PAPI_PRINTER_LARGE = 0x4000,	/* Can do D/E/A1/A0 */
219 	PAPI_PRINTER_VARIABLE = 0x8000,	/* Can do variable sizes */
220 	PAPI_PRINTER_IMPLICIT = 0x10000, /* implicit class */
221 	PAPI_PRINTER_DEFAULT = 0x20000,	/* Default printer on network */
222 	PAPI_PRINTER_OPTIONS = 0xfffc	/* ~ (CLASS | REMOTE | IMPLICIT) */
223 };
224 
225 /*
226  * Functions
227  */
228 
229 /* 	Service related		*/
230 extern papi_status_t papiServiceCreate(papi_service_t *handle,
231 					char *service_name, char *user_name,
232 					char *password,
233 					int (*authCB)(papi_service_t svc,
234 							void *app_data),
235 					papi_encryption_t encryption,
236 					void *app_data);
237 extern void papiServiceDestroy(papi_service_t handle);
238 extern papi_status_t papiServiceSetUserName(papi_service_t handle,
239 					char *user_name);
240 extern papi_status_t papiServiceSetPassword(papi_service_t handle,
241 					char *password);
242 extern papi_status_t papiServiceSetEncryption(papi_service_t handle,
243 					papi_encryption_t encryption);
244 extern papi_status_t papiServiceSetAuthCB(papi_service_t handle,
245 					int (*authCB)(papi_service_t s,
246 							void *app_data));
247 extern papi_status_t papiServiceSetAppData(papi_service_t handle,
248 					void *app_data);
249 extern char *papiServiceGetServiceName(papi_service_t handle);
250 extern char *papiServiceGetUserName(papi_service_t handle);
251 extern char *papiServiceGetPassword(papi_service_t handle);
252 extern papi_encryption_t papiServiceGetEncryption(papi_service_t handle);
253 extern void *papiServiceGetAppData(papi_service_t handle);
254 extern papi_attribute_t **papiServiceGetAttributeList(papi_service_t handle);
255 extern char *papiServiceGetStatusMessage(papi_service_t handle);
256 
257 /*	Attribute related	 */
258 extern papi_status_t papiAttributeListAddValue(papi_attribute_t ***attrs,
259 					int flags, char *name,
260 					papi_attribute_value_type_t type,
261 					papi_attribute_value_t *value);
262 extern papi_status_t papiAttributeListAddString(papi_attribute_t ***attrs,
263 					int flags, char *name, char *string);
264 extern papi_status_t papiAttributeListAddInteger(papi_attribute_t ***attrs,
265 					int flags, char *name, int integer);
266 extern papi_status_t papiAttributeListAddBoolean(papi_attribute_t ***attrs,
267 					int flags, char *name, char boolean);
268 extern papi_status_t papiAttributeListAddRange(papi_attribute_t ***attrs,
269 					int flags, char *name,
270 					int lower, int upper);
271 extern papi_status_t papiAttributeListAddResolution(papi_attribute_t ***attrs,
272 					int flags, char *name,
273 					int xres, int yres,
274 					papi_resolution_unit_t units);
275 extern papi_status_t papiAttributeListAddDatetime(papi_attribute_t ***attrs,
276 					int flags, char *name, time_t datetime);
277 extern papi_status_t papiAttributeListAddCollection(papi_attribute_t ***attrs,
278 					int flags, char *name,
279 					papi_attribute_t **collection);
280 extern papi_status_t papiAttributeListAddMetadata(papi_attribute_t ***attrs,
281 					int flags, char *name,
282 					papi_metadata_t metadata);
283 extern papi_status_t papiAttributeListDelete(papi_attribute_t ***attributes,
284 					char *name);
285 extern papi_status_t papiAttributeListGetValue(papi_attribute_t **list,
286 					void **iterator, char *name,
287 					papi_attribute_value_type_t type,
288 					papi_attribute_value_t **value);
289 extern papi_status_t papiAttributeListGetString(papi_attribute_t **list,
290 					void **iterator, char *name,
291 					char **vptr);
292 extern papi_status_t papiAttributeListGetInteger(papi_attribute_t **list,
293 					void **iterator, char *name, int *vptr);
294 extern papi_status_t papiAttributeListGetBoolean(papi_attribute_t **list,
295 					void **iterator, char *name,
296 					char *vptr);
297 extern papi_status_t papiAttributeListGetRange(papi_attribute_t **list,
298 					void **iterator, char *name,
299 					int *min, int *max);
300 extern papi_status_t papiAttributeListGetResolution(papi_attribute_t **list,
301 					void **iterator, char *name,
302 					int *x, int *y,
303 					papi_resolution_unit_t *units);
304 extern papi_status_t papiAttributeListGetDatetime(papi_attribute_t **list,
305 					void **iterator, char *name,
306 					time_t *dt);
307 extern papi_status_t papiAttributeListGetCollection(papi_attribute_t **list,
308 					void **iterator, char *name,
309 					papi_attribute_t ***collection);
310 extern papi_status_t papiAttributeListGetMetadata(papi_attribute_t **list,
311 					void **iterator, char *name,
312 					papi_metadata_t *vptr);
313 extern papi_attribute_t *papiAttributeListFind(papi_attribute_t **list,
314 					char *name);
315 extern papi_attribute_t *papiAttributeListGetNext(papi_attribute_t **list,
316 					void **iterator);
317 extern void papiAttributeListFree(papi_attribute_t **attributes);
318 
319 extern papi_status_t papiAttributeListFromString(papi_attribute_t ***attrs,
320 					int flags, char *string);
321 extern papi_status_t papiAttributeListToString(papi_attribute_t **attrs,
322 					char *delim,
323 					char *buffer, size_t buflen);
324 extern void papiAttributeListPrint(FILE *fp, papi_attribute_t **list,
325 					char *prefix_fmt, ...);
326 
327 /*	Printer related		 */
328 extern papi_status_t papiPrintersList(papi_service_t handle,
329 					char **requested_attrs,
330 					papi_filter_t *filter,
331 					papi_printer_t **printers);
332 extern papi_status_t papiPrinterQuery(papi_service_t handle, char *name,
333 					char **requested_attrs,
334 					papi_attribute_t **job_attributes,
335 					papi_printer_t *printer);
336 extern papi_status_t papiPrinterAdd(papi_service_t handle, char *name,
337 					papi_attribute_t **attributes,
338 					papi_printer_t *printer);
339 extern papi_status_t papiPrinterModify(papi_service_t handle, char *name,
340 					papi_attribute_t **attributes,
341 					papi_printer_t *printer);
342 extern papi_status_t papiPrinterRemove(papi_service_t handle, char *name);
343 extern papi_status_t papiPrinterDisable(papi_service_t handle, char *name,
344 					char *message);
345 extern papi_status_t papiPrinterEnable(papi_service_t handle, char *name);
346 extern papi_status_t papiPrinterPause(papi_service_t handle, char *name,
347 					char *message);
348 extern papi_status_t papiPrinterResume(papi_service_t handle, char *name);
349 extern papi_status_t papiPrinterPurgeJobs(papi_service_t handle,
350 					char *name, papi_job_t **jobs);
351 extern papi_status_t papiPrinterListJobs(papi_service_t handle,
352 					char *name, char **requested_attrs,
353 					int type_mask, int max_num_jobs,
354 					papi_job_t **jobs);
355 extern papi_attribute_t **papiPrinterGetAttributeList(papi_printer_t printer);
356 extern void papiPrinterFree(papi_printer_t printer);
357 extern void papiPrinterListFree(papi_printer_t *printers);
358 
359 /*	Job related		*/
360 extern papi_status_t papiJobSubmit(papi_service_t handle, char *printer,
361 					papi_attribute_t **job_attributes,
362 					papi_job_ticket_t *job_ticket,
363 					char **files, papi_job_t *job);
364 extern papi_status_t papiJobSubmitByReference(papi_service_t handle,
365 					char *printer,
366 					papi_attribute_t **job_attributes,
367 					papi_job_ticket_t *job_ticket,
368 					char **files, papi_job_t *job);
369 extern papi_status_t papiJobValidate(papi_service_t handle, char *printer,
370 					papi_attribute_t **job_attributes,
371 					papi_job_ticket_t *job_ticket,
372 					char **files, papi_job_t *job);
373 extern papi_status_t papiJobStreamOpen(papi_service_t handle,
374 					char *printer,
375 					papi_attribute_t **job_attributes,
376 					papi_job_ticket_t *job_ticket,
377 					papi_stream_t *stream);
378 extern papi_status_t papiJobStreamWrite(papi_service_t handle,
379 					papi_stream_t stream,
380 					void *buffer, size_t buflen);
381 extern papi_status_t papiJobStreamClose(papi_service_t handle,
382 					papi_stream_t stream,
383 					papi_job_t *job);
384 extern papi_status_t papiJobQuery(papi_service_t handle, char *printer,
385 					int32_t job_id, char **requested_attrs,
386 					papi_job_t *job);
387 extern papi_status_t papiJobModify(papi_service_t handle, char *printer,
388 					int32_t job_id,
389 					papi_attribute_t **attributes,
390 					papi_job_t *job);
391 extern papi_status_t papiJobMove(papi_service_t handle, char *printer,
392 					int32_t job_id, char *destination);
393 extern papi_status_t papiJobCancel(papi_service_t handle, char *printer,
394 					int32_t job_id);
395 extern papi_status_t papiJobHold(papi_service_t handle, char *printer,
396 					int32_t job_id);
397 extern papi_status_t papiJobRelease(papi_service_t handle, char *printer,
398 					int32_t job_id);
399 extern papi_status_t papiJobRestart(papi_service_t handle, char *printer,
400 					int32_t job_id);
401 extern papi_status_t papiJobPromote(papi_service_t handle, char *printer,
402 					int32_t job_id);
403 extern papi_attribute_t **papiJobGetAttributeList(papi_job_t printer);
404 extern char *papiJobGetPrinterName(papi_job_t printer);
405 extern int32_t papiJobGetId(papi_job_t printer);
406 extern papi_job_ticket_t *papiJobGetJobTicket(papi_job_t printer);
407 extern void papiJobFree(papi_job_t job);
408 extern void papiJobListFree(papi_job_t *jobs);
409 
410 #ifdef SOLARIS_PRIVATE_POST_0_9
411 /*
412  * These have been added to support IPP create-job/send-document with PAPI v0.9
413  * in an IPP listener using PAPI as it's spooler interface.  A future version
414  * of the API is expected to support this type of functionality
415  */
416 extern papi_status_t papiJobCreate(papi_service_t handle, char *printer,
417 					papi_attribute_t **job_attributes,
418 					papi_job_ticket_t *job_ticket,
419 					papi_job_t *job);
420 extern papi_status_t papiJobStreamAdd(papi_service_t handle, char *printer,
421 					int32_t id, papi_stream_t *stream);
422 extern papi_status_t papiJobCommit(papi_service_t handle, char *printer,
423 					int32_t id);
424 extern papi_status_t papiServiceSetPeer(papi_service_t handle, int peerfd);
425 #endif /* SOLARIS_PRIVATE_POST_0_9 */
426 
427 extern char *papiStatusString(papi_status_t status);
428 
429 /*
430  * Internal functions that aren't in the API, but are shared across
431  * protocol support implementations(psms) and the tightly bound
432  * listener library.  Do not use these in your applications.
433  */
434 extern void list_append();
435 extern void list_concatenate();
436 extern void list_remove();
437 extern void copy_attributes(papi_attribute_t ***result,
438 				papi_attribute_t **list);
439 extern void split_and_copy_attributes(char **list,
440 				papi_attribute_t **attributes,
441 				papi_attribute_t ***in,
442 				papi_attribute_t ***out);
443 
444 extern papi_attribute_t **getprinterbyname(char *name, char *ns);
445 
446 extern int is_localhost(char *hostname);
447 
448 #ifdef __cplusplus
449 }
450 #endif
451 
452 #endif /* _PAPI_H */
453