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