cups/ipp.h

   1 /*
   2  * "$Id: ipp.h 5090 2006-02-08 17:08:01Z mike $"
   3  *
   4  *   Internet Printing Protocol definitions for the Common UNIX Printing
   5  *   System (CUPS).
   6  *
   7  *   Copyright 1997-2006 by Easy Software Products.
   8  *
   9  *   These coded instructions, statements, and computer programs are the
  10  *   property of Easy Software Products and are protected by Federal
  11  *   copyright law.  Distribution and use rights are outlined in the file
  12  *   "LICENSE.txt" which should have been included with this file.  If this
  13  *   file is missing or damaged please contact Easy Software Products
  14  *   at:
  15  *
  16  *       Attn: CUPS Licensing Information
  17  *       Easy Software Products
  18  *       44141 Airport View Drive, Suite 204
  19  *       Hollywood, Maryland 20636 USA
  20  *
  21  *       Voice: (301) 373-9600
  22  *       EMail: cups-info@cups.org
  23  *         WWW: http://www.cups.org
  24  *
  25  *   This file is subject to the Apple OS-Developed Software exception.
  26  */
  27
  28 #ifndef _CUPS_IPP_H_
  29 #  define _CUPS_IPP_H_
  30
  31 /*
  32  * Include necessary headers...
  33  */
  34
  35 #  include "http.h"
  36
  37
  38 /*
  39  * C++ magic...
  40  */
  41
  42 #  ifdef __cplusplus
  43 extern "C" {
  44 #  endif /* __cplusplus */
  45
  46
  47 /*
  48  * IPP version string...
  49  */
  50
  51 #  define IPP_VERSION           "\001\001"
  52
  53 /*
  54  * IPP registered port number...
  55  *
  56  * Note: Applications should never use IPP_PORT, but instead use the
  57  * ippPort() function to allow overrides via the IPP_PORT environment
  58  * variable and services file if needed!
  59  */
  60
  61 #  define IPP_PORT              631
  62
  63 /*
  64  * Common limits...
  65  */
  66
  67 #  define IPP_MAX_NAME          256
  68 #  define IPP_MAX_VALUES        8       /* Power-of-2 allocation increment */
  69
  70
  71 /*
  72  * Types and structures...
  73  */
  74
  75 typedef enum                            /**** Format tags for attribute formats... ****/
  76 {
  77   IPP_TAG_ZERO = 0x00,
  78   IPP_TAG_OPERATION,
  79   IPP_TAG_JOB,
  80   IPP_TAG_END,
  81   IPP_TAG_PRINTER,
  82   IPP_TAG_UNSUPPORTED_GROUP,
  83   IPP_TAG_SUBSCRIPTION,
  84   IPP_TAG_EVENT_NOTIFICATION,
  85   IPP_TAG_UNSUPPORTED_VALUE = 0x10,
  86   IPP_TAG_DEFAULT,
  87   IPP_TAG_UNKNOWN,
  88   IPP_TAG_NOVALUE,
  89   IPP_TAG_NOTSETTABLE = 0x15,
  90   IPP_TAG_DELETEATTR,
  91   IPP_TAG_ADMINDEFINE,
  92   IPP_TAG_INTEGER = 0x21,
  93   IPP_TAG_BOOLEAN,
  94   IPP_TAG_ENUM,
  95   IPP_TAG_STRING = 0x30,
  96   IPP_TAG_DATE,
  97   IPP_TAG_RESOLUTION,
  98   IPP_TAG_RANGE,
  99   IPP_TAG_BEGIN_COLLECTION,
 100   IPP_TAG_TEXTLANG,
 101   IPP_TAG_NAMELANG,
 102   IPP_TAG_END_COLLECTION,
 103   IPP_TAG_TEXT = 0x41,
 104   IPP_TAG_NAME,
 105   IPP_TAG_KEYWORD = 0x44,
 106   IPP_TAG_URI,
 107   IPP_TAG_URISCHEME,
 108   IPP_TAG_CHARSET,
 109   IPP_TAG_LANGUAGE,
 110   IPP_TAG_MIMETYPE,
 111   IPP_TAG_MEMBERNAME,
 112   IPP_TAG_MASK = 0x7fffffff,            /* Mask for copied attribute values */
 113   IPP_TAG_COPY = -0x7fffffff-1          /* Bitflag for copied attribute values */
 114 } ipp_tag_t;
 115
 116 typedef enum                            /**** Resolution units... ****/
 117 {
 118   IPP_RES_PER_INCH = 3,
 119   IPP_RES_PER_CM
 120 } ipp_res_t;
 121
 122 typedef enum                            /**** Finishings... ****/
 123 {
 124   IPP_FINISHINGS_NONE = 3,
 125   IPP_FINISHINGS_STAPLE,
 126   IPP_FINISHINGS_PUNCH,
 127   IPP_FINISHINGS_COVER,
 128   IPP_FINISHINGS_BIND,
 129   IPP_FINISHINGS_SADDLE_STITCH,
 130   IPP_FINISHINGS_EDGE_STITCH,
 131   IPP_FINISHINGS_FOLD,
 132   IPP_FINISHINGS_TRIM,
 133   IPP_FINISHINGS_BALE,
 134   IPP_FINISHINGS_BOOKLET_MAKER,
 135   IPP_FINISHINGS_JOB_OFFSET,
 136   IPP_FINISHINGS_STAPLE_TOP_LEFT = 20,
 137   IPP_FINISHINGS_STAPLE_BOTTOM_LEFT,
 138   IPP_FINISHINGS_STAPLE_TOP_RIGHT,
 139   IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT,
 140   IPP_FINISHINGS_EDGE_STITCH_LEFT,
 141   IPP_FINISHINGS_EDGE_STITCH_TOP,
 142   IPP_FINISHINGS_EDGE_STITCH_RIGHT,
 143   IPP_FINISHINGS_EDGE_STITCH_BOTTOM,
 144   IPP_FINISHINGS_STAPLE_DUAL_LEFT,
 145   IPP_FINISHINGS_STAPLE_DUAL_TOP,
 146   IPP_FINISHINGS_STAPLE_DUAL_RIGHT,
 147   IPP_FINISHINGS_STAPLE_DUAL_BOTTOM,
 148   IPP_FINISHINGS_BIND_LEFT = 50,
 149   IPP_FINISHINGS_BIND_TOP,
 150   IPP_FINISHINGS_BIND_RIGHT,
 151   IPP_FINISHINGS_BIND_BOTTOM
 152 } ipp_finish_t;
 153
 154 typedef enum                            /**** Orientation... ****/
 155 {
 156   IPP_PORTRAIT = 3,                     /* No rotation */
 157   IPP_LANDSCAPE,                        /* 90 degrees counter-clockwise */
 158   IPP_REVERSE_LANDSCAPE,                /* 90 degrees clockwise */
 159   IPP_REVERSE_PORTRAIT                  /* 180 degrees */
 160 } ipp_orient_t;
 161
 162 typedef enum                            /**** Qualities... ****/
 163 {
 164   IPP_QUALITY_DRAFT = 3,
 165   IPP_QUALITY_NORMAL,
 166   IPP_QUALITY_HIGH
 167 } ipp_quality_t;
 168
 169 typedef enum                            /**** Job States.... */
 170 {
 171   IPP_JOB_PENDING = 3,
 172   IPP_JOB_HELD,
 173   IPP_JOB_PROCESSING,
 174   IPP_JOB_STOPPED,
 175   IPP_JOB_CANCELLED,
 176   IPP_JOB_ABORTED,
 177   IPP_JOB_COMPLETED
 178 } ipp_jstate_t;
 179
 180 typedef enum                            /**** Printer States.... */
 181 {
 182   IPP_PRINTER_IDLE = 3,
 183   IPP_PRINTER_PROCESSING,
 184   IPP_PRINTER_STOPPED
 185 } ipp_pstate_t;
 186
 187 typedef enum                            /**** IPP states... ****/
 188 {
 189   IPP_ERROR = -1,                       /* An error occurred */
 190   IPP_IDLE,                             /* Nothing is happening/request completed */
 191   IPP_HEADER,                           /* The request header needs to be sent/received */
 192   IPP_ATTRIBUTE,                        /* One or more attributes need to be sent/received */
 193   IPP_DATA                              /* IPP request data needs to be sent/received */
 194 } ipp_state_t;
 195
 196 typedef enum                            /**** IPP operations... ****/
 197 {
 198   IPP_PRINT_JOB = 0x0002,
 199   IPP_PRINT_URI,
 200   IPP_VALIDATE_JOB,
 201   IPP_CREATE_JOB,
 202   IPP_SEND_DOCUMENT,
 203   IPP_SEND_URI,
 204   IPP_CANCEL_JOB,
 205   IPP_GET_JOB_ATTRIBUTES,
 206   IPP_GET_JOBS,
 207   IPP_GET_PRINTER_ATTRIBUTES,
 208   IPP_HOLD_JOB,
 209   IPP_RELEASE_JOB,
 210   IPP_RESTART_JOB,
 211   IPP_PAUSE_PRINTER = 0x0010,
 212   IPP_RESUME_PRINTER,
 213   IPP_PURGE_JOBS,
 214   IPP_SET_PRINTER_ATTRIBUTES,
 215   IPP_SET_JOB_ATTRIBUTES,
 216   IPP_GET_PRINTER_SUPPORTED_VALUES,
 217   IPP_CREATE_PRINTER_SUBSCRIPTION,
 218   IPP_CREATE_JOB_SUBSCRIPTION,
 219   IPP_GET_SUBSCRIPTION_ATTRIBUTES,
 220   IPP_GET_SUBSCRIPTIONS,
 221   IPP_RENEW_SUBSCRIPTION,
 222   IPP_CANCEL_SUBSCRIPTION,
 223   IPP_GET_NOTIFICATIONS,
 224   IPP_SEND_NOTIFICATIONS,
 225   IPP_GET_PRINT_SUPPORT_FILES = 0x0021,
 226   IPP_ENABLE_PRINTER,
 227   IPP_DISABLE_PRINTER,
 228   IPP_PAUSE_PRINTER_AFTER_CURRENT_JOB,
 229   IPP_HOLD_NEW_JOBS,
 230   IPP_RELEASE_HELD_NEW_JOBS,
 231   IPP_DEACTIVATE_PRINTER,
 232   IPP_ACTIVATE_PRINTER,
 233   IPP_RESTART_PRINTER,
 234   IPP_SHUTDOWN_PRINTER,
 235   IPP_STARTUP_PRINTER,
 236   IPP_REPROCESS_JOB,
 237   IPP_CANCEL_CURRENT_JOB,
 238   IPP_SUSPEND_CURRENT_JOB,
 239   IPP_RESUME_JOB,
 240   IPP_PROMOTE_JOB,
 241   IPP_SCHEDULE_JOB_AFTER,
 242   IPP_PRIVATE = 0x4000,
 243   CUPS_GET_DEFAULT,
 244   CUPS_GET_PRINTERS,
 245   CUPS_ADD_MODIFY_PRINTER,
 246   CUPS_DELETE_PRINTER,
 247   CUPS_GET_CLASSES,
 248   CUPS_ADD_MODIFY_CLASS,
 249   CUPS_DELETE_CLASS,
 250   CUPS_ACCEPT_JOBS,
 251   CUPS_REJECT_JOBS,
 252   CUPS_SET_DEFAULT,
 253   CUPS_GET_DEVICES,
 254   CUPS_GET_PPDS,
 255   CUPS_MOVE_JOB,
 256   CUPS_AUTHENTICATE_JOB
 257 } ipp_op_t;
 258
 259 /* Old names for the operations */
 260 #define CUPS_ADD_PRINTER        CUPS_ADD_MODIFY_PRINTER
 261 #define CUPS_ADD_CLASS          CUPS_ADD_MODIFY_CLASS
 262
 263 typedef enum                            /**** IPP status codes... ****/
 264 {
 265   IPP_OK = 0x0000,
 266   IPP_OK_SUBST,
 267   IPP_OK_CONFLICT,
 268   IPP_OK_IGNORED_SUBSCRIPTIONS,
 269   IPP_OK_IGNORED_NOTIFICATIONS,
 270   IPP_OK_TOO_MANY_EVENTS,
 271   IPP_OK_BUT_CANCEL_SUBSCRIPTION,
 272   IPP_OK_EVENTS_COMPLETE,
 273   IPP_REDIRECTION_OTHER_SITE = 0x300,
 274   IPP_BAD_REQUEST = 0x0400,
 275   IPP_FORBIDDEN,
 276   IPP_NOT_AUTHENTICATED,
 277   IPP_NOT_AUTHORIZED,
 278   IPP_NOT_POSSIBLE,
 279   IPP_TIMEOUT,
 280   IPP_NOT_FOUND,
 281   IPP_GONE,
 282   IPP_REQUEST_ENTITY,
 283   IPP_REQUEST_VALUE,
 284   IPP_DOCUMENT_FORMAT,
 285   IPP_ATTRIBUTES,
 286   IPP_URI_SCHEME,
 287   IPP_CHARSET,
 288   IPP_CONFLICT,
 289   IPP_COMPRESSION_NOT_SUPPORTED,
 290   IPP_COMPRESSION_ERROR,
 291   IPP_DOCUMENT_FORMAT_ERROR,
 292   IPP_DOCUMENT_ACCESS_ERROR,
 293   IPP_ATTRIBUTES_NOT_SETTABLE,
 294   IPP_IGNORED_ALL_SUBSCRIPTIONS,
 295   IPP_TOO_MANY_SUBSCRIPTIONS,
 296   IPP_IGNORED_ALL_NOTIFICATIONS,
 297   IPP_PRINT_SUPPORT_FILE_NOT_FOUND,
 298
 299   IPP_INTERNAL_ERROR = 0x0500,
 300   IPP_OPERATION_NOT_SUPPORTED,
 301   IPP_SERVICE_UNAVAILABLE,
 302   IPP_VERSION_NOT_SUPPORTED,
 303   IPP_DEVICE_ERROR,
 304   IPP_TEMPORARY_ERROR,
 305   IPP_NOT_ACCEPTING,
 306   IPP_PRINTER_BUSY,
 307   IPP_ERROR_JOB_CANCELLED,
 308   IPP_MULTIPLE_JOBS_NOT_SUPPORTED,
 309   IPP_PRINTER_IS_DEACTIVATED
 310 } ipp_status_t;
 311
 312 typedef unsigned char ipp_uchar_t;      /**** Unsigned 8-bit integer/character ****/
 313
 314 /**** New in CUPS 1.2 ****/
 315 typedef ssize_t (*ipp_iocb_t)(void *, ipp_uchar_t *, size_t);
 316                                         /**** IPP IO Callback Function @since CUPS 1.2@ ****/
 317
 318 typedef union                           /**** Request Header ****/
 319 {
 320   struct                                /* Any Header */
 321   {
 322     ipp_uchar_t version[2];             /* Protocol version number */
 323     int         op_status;              /* Operation ID or status code*/
 324     int         request_id;             /* Request ID */
 325   }             any;
 326
 327   struct                                /* Operation Header */
 328   {
 329     ipp_uchar_t version[2];             /* Protocol version number */
 330     ipp_op_t    operation_id;           /* Operation ID */
 331     int         request_id;             /* Request ID */
 332   }             op;
 333
 334   struct                                /* Status Header */
 335   {
 336     ipp_uchar_t version[2];             /* Protocol version number */
 337     ipp_status_t status_code;           /* Status code */
 338     int         request_id;             /* Request ID */
 339   }             status;
 340
 341   /**** New in CUPS 1.1.19 ****/
 342   struct                                /* Event Header */
 343   {
 344     ipp_uchar_t version[2];             /* Protocol version number */
 345     ipp_status_t status_code;           /* Status code */
 346     int         request_id;             /* Request ID */
 347   }             event;
 348 } ipp_request_t;
 349
 350 /**** New in CUPS 1.1.19 ****/
 351 typedef struct ipp_str ipp_t;
 352
 353 typedef union                           /**** Attribute Value ****/
 354 {
 355   int           integer;                /* Integer/enumerated value */
 356
 357   char          boolean;                /* Boolean value */
 358
 359   ipp_uchar_t   date[11];               /* Date/time value */
 360
 361   struct
 362   {
 363     int         xres,                   /* Horizontal resolution */
 364                 yres;                   /* Vertical resolution */
 365     ipp_res_t   units;                  /* Resolution units */
 366   }             resolution;             /* Resolution value */
 367
 368   struct
 369   {
 370     int         lower,                  /* Lower value */
 371                 upper;                  /* Upper value */
 372   }             range;                  /* Range of integers value */
 373
 374   struct
 375   {
 376     char        *charset;               /* Character set */
 377     char        *text;                  /* String */
 378   }             string;                 /* String with language value */
 379
 380   struct
 381   {
 382     int         length;                 /* Length of attribute */
 383     void        *data;                  /* Data in attribute */
 384   }             unknown;                /* Unknown attribute type */
 385
 386 /**** New in CUPS 1.1.19 ****/
 387   ipp_t         *collection;            /* Collection value */
 388 } ipp_value_t;
 389
 390 typedef struct ipp_attribute_s          /**** Attribute ****/
 391 {
 392   struct ipp_attribute_s *next;         /* Next attribute in list */
 393   ipp_tag_t     group_tag,              /* Job/Printer/Operation group tag */
 394                 value_tag;              /* What type of value is it? */
 395   char          *name;                  /* Name of attribute */
 396   int           num_values;             /* Number of values */
 397   ipp_value_t   values[1];              /* Values */
 398 } ipp_attribute_t;
 399
 400 struct ipp_str                          /**** IPP Request/Response/Notification ****/
 401 {
 402   ipp_state_t   state;                  /* State of request */
 403   ipp_request_t request;                /* Request header */
 404   ipp_attribute_t *attrs,               /* Attributes */
 405                 *last,                  /* Last attribute in list */
 406                 *current;               /* Current attribute (for read/write) */
 407   ipp_tag_t     curtag;                 /* Current attribute group tag */
 408
 409 /**** New in CUPS 1.2 ****/
 410   ipp_attribute_t *prev;                /* Previous attribute (for read) */
 411 };
 412
 413
 414 /*
 415  * Prototypes...
 416  */
 417
 418 extern ipp_attribute_t  *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
 419                                        const char *name, char value);
 420 extern ipp_attribute_t  *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
 421                                         const char *name, int num_values,
 422                                         const char *values);
 423 extern ipp_attribute_t  *ippAddDate(ipp_t *ipp, ipp_tag_t group,
 424                                     const char *name, const ipp_uchar_t *value);
 425 extern ipp_attribute_t  *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
 426                                        ipp_tag_t type, const char *name,
 427                                        int value);
 428 extern ipp_attribute_t  *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
 429                                         ipp_tag_t type, const char *name,
 430                                         int num_values, const int *values);
 431 extern ipp_attribute_t  *ippAddRange(ipp_t *ipp, ipp_tag_t group,
 432                                      const char *name, int lower, int upper);
 433 extern ipp_attribute_t  *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
 434                                       const char *name, int num_values,
 435                                       const int *lower, const int *upper);
 436 extern ipp_attribute_t  *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
 437                                           const char *name, ipp_res_t units,
 438                                           int xres, int yres);
 439 extern ipp_attribute_t  *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
 440                                            const char *name, int num_values,
 441                                            ipp_res_t units, const int *xres,
 442                                            const int *yres);
 443 extern ipp_attribute_t  *ippAddSeparator(ipp_t *ipp);
 444 extern ipp_attribute_t  *ippAddString(ipp_t *ipp, ipp_tag_t group,
 445                                       ipp_tag_t type, const char *name,
 446                                       const char *charset, const char *value);
 447 extern ipp_attribute_t  *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
 448                                        ipp_tag_t type, const char *name,
 449                                        int num_values, const char *charset,
 450                                        const char * const *values);
 451 extern time_t           ippDateToTime(const ipp_uchar_t *date);
 452 extern void             ippDelete(ipp_t *ipp);
 453 extern const char       *ippErrorString(ipp_status_t error);
 454 extern ipp_attribute_t  *ippFindAttribute(ipp_t *ipp, const char *name,
 455                                           ipp_tag_t type);
 456 extern ipp_attribute_t  *ippFindNextAttribute(ipp_t *ipp, const char *name,
 457                                               ipp_tag_t type);
 458 extern size_t           ippLength(ipp_t *ipp);
 459 extern ipp_t            *ippNew(void);
 460 extern ipp_state_t      ippRead(http_t *http, ipp_t *ipp);
 461 extern const ipp_uchar_t *ippTimeToDate(time_t t);
 462 extern ipp_state_t      ippWrite(http_t *http, ipp_t *ipp);
 463 extern int              ippPort(void);
 464 extern void             ippSetPort(int p);
 465
 466 /**** New in CUPS 1.1.19 ****/
 467 extern ipp_attribute_t  *ippAddCollection(ipp_t *ipp, ipp_tag_t group,
 468                                           const char *name, ipp_t *value);
 469 extern ipp_attribute_t  *ippAddCollections(ipp_t *ipp, ipp_tag_t group,
 470                                            const char *name, int num_values,
 471                                            const ipp_t **values);
 472 extern void             ippDeleteAttribute(ipp_t *ipp, ipp_attribute_t *attr);
 473 extern ipp_state_t      ippReadFile(int fd, ipp_t *ipp);
 474 extern ipp_state_t      ippWriteFile(int fd, ipp_t *ipp);
 475
 476 /**** New in CUPS 1.2 ****/
 477 extern ipp_attribute_t  *ippAddOctetString(ipp_t *ipp, ipp_tag_t group,
 478                                            const char *name,
 479                                            const void *data, int datalen);
 480 extern ipp_status_t     ippErrorValue(const char *name);
 481 extern ipp_t            *ippNewRequest(ipp_op_t op);
 482 extern const char       *ippOpString(ipp_op_t op);
 483 extern ipp_op_t         ippOpValue(const char *name);
 484 extern ipp_state_t      ippReadIO(void *src, ipp_iocb_t cb, int blocking,
 485                                   ipp_t *parent, ipp_t *ipp);
 486 extern ipp_state_t      ippWriteIO(void *dst, ipp_iocb_t cb, int blocking,
 487                                    ipp_t *parent, ipp_t *ipp);
 488
 489
 490 /*
 491  * C++ magic...
 492  */
 493
 494 #  ifdef __cplusplus
 495 }
 496 #  endif /* __cplusplus */
 497 #endif /* !_CUPS_IPP_H_ */
 498
 499 /*
 500  * End of "$Id: ipp.h 5090 2006-02-08 17:08:01Z mike $".
 501  */