usr/src/lib/print/libpapi-common/common/papi.h

   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 */