cups/cups.h

   1 /*
   2  * "$Id: cups.h 8781 2009-08-28 17:34:54Z mike $"
   3  *
   4  *   API definitions for CUPS.
   5  *
   6  *   Copyright 2007-2011 by Apple Inc.
   7  *   Copyright 1997-2007 by Easy Software Products.
   8  *
   9  *   These coded instructions, statements, and computer programs are the
  10  *   property of Apple Inc. and are protected by Federal copyright
  11  *   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  12  *   which should have been included with this file.  If this file is
  13  *   file is missing or damaged, see the license at "http://www.cups.org/".
  14  *
  15  *   This file is subject to the Apple OS-Developed Software exception.
  16  */
  17
  18 #ifndef _CUPS_CUPS_H_
  19 #  define _CUPS_CUPS_H_
  20
  21 /*
  22  * Include necessary headers...
  23  */
  24
  25 #  include <sys/types.h>
  26 #  if defined(WIN32) && !defined(__CUPS_SSIZE_T_DEFINED)
  27 #    define __CUPS_SSIZE_T_DEFINED
  28 #    include <stddef.h>
  29 /* Windows does not support the ssize_t type, so map it to off_t... */
  30 typedef off_t ssize_t;                  /* @private@ */
  31 #  endif /* WIN32 && !__CUPS_SSIZE_T_DEFINED */
  32
  33 #  ifdef __BLOCKS__
  34 #    include <dispatch/dispatch.h>
  35 #  endif /* __BLOCKS__ */
  36
  37 #  include "file.h"
  38 #  include "ipp.h"
  39 #  include "language.h"
  40
  41
  42 /*
  43  * C++ magic...
  44  */
  45
  46 #  ifdef __cplusplus
  47 extern "C" {
  48 #  endif /* __cplusplus */
  49
  50
  51 /*
  52  * Constants...
  53  */
  54
  55 #  define CUPS_VERSION          1.0599
  56 #  define CUPS_VERSION_MAJOR    1
  57 #  define CUPS_VERSION_MINOR    6
  58 #  define CUPS_VERSION_PATCH    -1
  59
  60 #  define CUPS_BC_FD            3       /* Back-channel file descriptor for select/poll */
  61 #  define CUPS_DATE_ANY         (time_t)-1
  62 #  define CUPS_EXCLUDE_NONE     (const char *)0
  63 #  define CUPS_FORMAT_AUTO      "application/octet-stream"
  64 #  define CUPS_FORMAT_COMMAND   "application/vnd.cups-command"
  65 #  define CUPS_FORMAT_PDF       "application/pdf"
  66 #  define CUPS_FORMAT_POSTSCRIPT "application/postscript"
  67 #  define CUPS_FORMAT_RAW       "application/vnd.cups-raw"
  68 #  define CUPS_FORMAT_TEXT      "text/plain"
  69 #  define CUPS_HTTP_DEFAULT     (http_t *)0
  70 #  define CUPS_INCLUDE_ALL      (const char *)0
  71 #  define CUPS_JOBID_ALL        -1
  72 #  define CUPS_JOBID_CURRENT    0
  73 #  define CUPS_LENGTH_VARIABLE  (ssize_t)0
  74 #  define CUPS_TIMEOUT_DEFAULT  0
  75 #  define CUPS_WHICHJOBS_ALL    -1
  76 #  define CUPS_WHICHJOBS_ACTIVE 0
  77 #  define CUPS_WHICHJOBS_COMPLETED 1
  78
  79
  80 /*
  81  * Types and structures...
  82  */
  83
  84 typedef unsigned cups_ptype_t;          /**** Printer type/capability bits ****/
  85 enum cups_ptype_e                       /**** Printer type/capability bit constants ****/
  86 {                                       /* Not a typedef'd enum so we can OR */
  87   CUPS_PRINTER_LOCAL = 0x0000,          /* Local printer or class */
  88   CUPS_PRINTER_CLASS = 0x0001,          /* Printer class */
  89   CUPS_PRINTER_REMOTE = 0x0002,         /* Remote printer or class */
  90   CUPS_PRINTER_BW = 0x0004,             /* Can do B&W printing */
  91   CUPS_PRINTER_COLOR = 0x0008,          /* Can do color printing */
  92   CUPS_PRINTER_DUPLEX = 0x0010,         /* Can do duplexing */
  93   CUPS_PRINTER_STAPLE = 0x0020,         /* Can staple output */
  94   CUPS_PRINTER_COPIES = 0x0040,         /* Can do copies */
  95   CUPS_PRINTER_COLLATE = 0x0080,        /* Can collage copies */
  96   CUPS_PRINTER_PUNCH = 0x0100,          /* Can punch output */
  97   CUPS_PRINTER_COVER = 0x0200,          /* Can cover output */
  98   CUPS_PRINTER_BIND = 0x0400,           /* Can bind output */
  99   CUPS_PRINTER_SORT = 0x0800,           /* Can sort output */
 100   CUPS_PRINTER_SMALL = 0x1000,          /* Can do Letter/Legal/A4 */
 101   CUPS_PRINTER_MEDIUM = 0x2000,         /* Can do Tabloid/B/C/A3/A2 */
 102   CUPS_PRINTER_LARGE = 0x4000,          /* Can do D/E/A1/A0 */
 103   CUPS_PRINTER_VARIABLE = 0x8000,       /* Can do variable sizes */
 104   CUPS_PRINTER_IMPLICIT = 0x10000,      /* Implicit class @private@ @since Deprecated@ */
 105   CUPS_PRINTER_DEFAULT = 0x20000,       /* Default printer on network */
 106   CUPS_PRINTER_FAX = 0x40000,           /* Fax queue */
 107   CUPS_PRINTER_REJECTING = 0x80000,     /* Printer is rejecting jobs */
 108   CUPS_PRINTER_DELETE = 0x100000,       /* Delete printer @since CUPS 1.2/Mac OS X 10.5@ */
 109   CUPS_PRINTER_NOT_SHARED = 0x200000,   /* Printer is not shared @since CUPS 1.2/Mac OS X 10.5@ */
 110   CUPS_PRINTER_AUTHENTICATED = 0x400000,/* Printer requires authentication @since CUPS 1.2/Mac OS X 10.5@ */
 111   CUPS_PRINTER_COMMANDS = 0x800000,     /* Printer supports maintenance commands @since CUPS 1.2/Mac OS X 10.5@ */
 112   CUPS_PRINTER_DISCOVERED = 0x1000000,  /* Printer was automatically discovered and added @private@ @since Deprecated@ */
 113   CUPS_PRINTER_SCANNER = 0x2000000,     /* Scanner-only device @since CUPS 1.4/Mac OS X 10.6@ */
 114   CUPS_PRINTER_MFP = 0x4000000,         /* Printer with scanning capabilities @since CUPS 1.4/Mac OS X 10.6@ */
 115   CUPS_PRINTER_OPTIONS = 0x6fffc        /* ~(CLASS | REMOTE | IMPLICIT | DEFAULT | FAX | REJECTING | DELETE | NOT_SHARED | AUTHENTICATED | COMMANDS | DISCOVERED) @private@ */
 116 };
 117
 118 typedef struct cups_option_s            /**** Printer Options ****/
 119 {
 120   char          *name;                  /* Name of option */
 121   char          *value;                 /* Value of option */
 122 } cups_option_t;
 123
 124 typedef struct cups_dest_s              /**** Destination ****/
 125 {
 126   char          *name,                  /* Printer or class name */
 127                 *instance;              /* Local instance name or NULL */
 128   int           is_default;             /* Is this printer the default? */
 129   int           num_options;            /* Number of options */
 130   cups_option_t *options;               /* Options */
 131 } cups_dest_t;
 132
 133 typedef struct cups_job_s               /**** Job ****/
 134 {
 135   int           id;                     /* The job ID */
 136   char          *dest;                  /* Printer or class name */
 137   char          *title;                 /* Title/job name */
 138   char          *user;                  /* User the submitted the job */
 139   char          *format;                /* Document format */
 140   ipp_jstate_t  state;                  /* Job state */
 141   int           size;                   /* Size in kilobytes */
 142   int           priority;               /* Priority (1-100) */
 143   time_t        completed_time;         /* Time the job was completed */
 144   time_t        creation_time;          /* Time the job was created */
 145   time_t        processing_time;        /* Time the job was processed */
 146 } cups_job_t;
 147
 148 typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls,
 149                                      cups_array_t *distinguished_names,
 150                                      void *user_data);
 151                                         /**** Client credentials callback @since CUPS 1.5/Mac OS X 10.7@ ****/
 152
 153 typedef int (*cups_dest_cb_t)(void *user_data, const char *name, const char *instance,
 154                               int num_options, cups_option_t *options);
 155                                         /**** Destination enumeration callback @since CUPS 1.6@ ****/
 156
 157 #  ifdef __BLOCKS__
 158 typedef int (^cups_dest_block_t)(const char *name, const char *instance, int num_options,
 159                                  cups_option_t *options);
 160                                         /**** Destination enumeration block @since CUPS 1.6@ ****/
 161 #  endif /* __BLOCKS__ */
 162
 163 typedef void (*cups_device_cb_t)(const char *device_class,
 164                                  const char *device_id, const char *device_info,
 165                                  const char *device_make_and_model,
 166                                  const char *device_uri,
 167                                  const char *device_location, void *user_data);
 168                                         /**** Device callback @since CUPS 1.4/Mac OS X 10.6@ ****/
 169
 170 typedef const char *(*cups_password_cb_t)(const char *prompt);
 171                                         /**** Password callback ****/
 172
 173 typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http,
 174                                            const char *method,
 175                                            const char *resource,
 176                                            void *user_data);
 177                                         /**** New password callback @since CUPS 1.4/Mac OS X 10.6@ ****/
 178
 179 typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls,
 180                                      cups_array_t *certs, void *user_data);
 181                                         /**** Server credentials callback @since CUPS 1.5/Mac OS X 10.7@ ****/
 182
 183
 184 /*
 185  * Functions...
 186  */
 187
 188 extern int              cupsCancelJob(const char *name, int job_id);
 189 extern ipp_t            *cupsDoFileRequest(http_t *http, ipp_t *request,
 190                                            const char *resource,
 191                                            const char *filename);
 192 extern ipp_t            *cupsDoRequest(http_t *http, ipp_t *request,
 193                                        const char *resource);
 194 extern http_encryption_t cupsEncryption(void);
 195 extern void             cupsFreeJobs(int num_jobs, cups_job_t *jobs);
 196 extern int              cupsGetClasses(char ***classes) _CUPS_DEPRECATED;
 197 extern const char       *cupsGetDefault(void);
 198 extern int              cupsGetJobs(cups_job_t **jobs, const char *name,
 199                                     int myjobs, int whichjobs);
 200 extern const char       *cupsGetPPD(const char *name);
 201 extern int              cupsGetPrinters(char ***printers) _CUPS_DEPRECATED;
 202 extern ipp_status_t     cupsLastError(void);
 203 extern int              cupsPrintFile(const char *name, const char *filename,
 204                                       const char *title, int num_options,
 205                                       cups_option_t *options);
 206 extern int              cupsPrintFiles(const char *name, int num_files,
 207                                        const char **files, const char *title,
 208                                        int num_options, cups_option_t *options);
 209 extern char             *cupsTempFile(char *filename, int len) _CUPS_DEPRECATED;
 210 extern int              cupsTempFd(char *filename, int len);
 211
 212 extern int              cupsAddDest(const char *name, const char *instance,
 213                                     int num_dests, cups_dest_t **dests);
 214 extern void             cupsFreeDests(int num_dests, cups_dest_t *dests);
 215 extern cups_dest_t      *cupsGetDest(const char *name, const char *instance,
 216                                      int num_dests, cups_dest_t *dests);
 217 extern int              cupsGetDests(cups_dest_t **dests);
 218 extern void             cupsSetDests(int num_dests, cups_dest_t *dests);
 219
 220 extern int              cupsAddOption(const char *name, const char *value,
 221                                       int num_options, cups_option_t **options);
 222 extern void             cupsEncodeOptions(ipp_t *ipp, int num_options,
 223                                           cups_option_t *options);
 224 extern void             cupsFreeOptions(int num_options, cups_option_t *options);
 225 extern const char       *cupsGetOption(const char *name, int num_options,
 226                                        cups_option_t *options);
 227 extern int              cupsParseOptions(const char *arg, int num_options,
 228                                          cups_option_t **options);
 229
 230 extern const char       *cupsGetPassword(const char *prompt);
 231 extern const char       *cupsServer(void);
 232 extern void             cupsSetEncryption(http_encryption_t e);
 233 extern void             cupsSetPasswordCB(cups_password_cb_t cb);
 234 extern void             cupsSetServer(const char *server);
 235 extern void             cupsSetUser(const char *user);
 236 extern const char       *cupsUser(void);
 237
 238 /**** New in CUPS 1.1.20 ****/
 239 extern int              cupsDoAuthentication(http_t *http, const char *method,
 240                                              const char *resource) _CUPS_API_1_1_20;
 241 extern http_status_t    cupsGetFile(http_t *http, const char *resource,
 242                                     const char *filename) _CUPS_API_1_1_20;
 243 extern http_status_t    cupsGetFd(http_t *http, const char *resource, int fd);
 244 extern http_status_t    cupsPutFile(http_t *http, const char *resource,
 245                                     const char *filename) _CUPS_API_1_1_20;
 246 extern http_status_t    cupsPutFd(http_t *http, const char *resource, int fd) _CUPS_API_1_1_20;
 247
 248 /**** New in CUPS 1.1.21 ****/
 249 extern const char       *cupsGetDefault2(http_t *http) _CUPS_API_1_1_21;
 250 extern int              cupsGetDests2(http_t *http, cups_dest_t **dests) _CUPS_API_1_1_21;
 251 extern int              cupsGetJobs2(http_t *http, cups_job_t **jobs,
 252                                      const char *name, int myjobs,
 253                                      int whichjobs) _CUPS_API_1_1_21;
 254 extern const char       *cupsGetPPD2(http_t *http, const char *name) _CUPS_API_1_1_21;
 255 extern int              cupsPrintFile2(http_t *http, const char *name,
 256                                        const char *filename,
 257                                        const char *title, int num_options,
 258                                        cups_option_t *options) _CUPS_API_1_1_21;
 259 extern int              cupsPrintFiles2(http_t *http, const char *name,
 260                                         int num_files, const char **files,
 261                                         const char *title, int num_options,
 262                                         cups_option_t *options) _CUPS_API_1_1_21;
 263 extern int              cupsSetDests2(http_t *http, int num_dests,
 264                                       cups_dest_t *dests) _CUPS_API_1_1_21;
 265
 266 /**** New in CUPS 1.2/Mac OS X 10.5 ****/
 267 extern ssize_t          cupsBackChannelRead(char *buffer, size_t bytes,
 268                                             double timeout) _CUPS_API_1_2;
 269 extern ssize_t          cupsBackChannelWrite(const char *buffer, size_t bytes,
 270                                              double timeout) _CUPS_API_1_2;
 271 extern void             cupsEncodeOptions2(ipp_t *ipp, int num_options,
 272                                            cups_option_t *options,
 273                                            ipp_tag_t group_tag) _CUPS_API_1_2;
 274 extern const char       *cupsLastErrorString(void) _CUPS_API_1_2;
 275 extern char             *cupsNotifySubject(cups_lang_t *lang, ipp_t *event) _CUPS_API_1_2;
 276 extern char             *cupsNotifyText(cups_lang_t *lang, ipp_t *event) _CUPS_API_1_2;
 277 extern int              cupsRemoveOption(const char *name, int num_options,
 278                                          cups_option_t **options) _CUPS_API_1_2;
 279 extern cups_file_t      *cupsTempFile2(char *filename, int len) _CUPS_API_1_2;
 280
 281 /**** New in CUPS 1.3/Mac OS X 10.5 ****/
 282 extern ipp_t            *cupsDoIORequest(http_t *http, ipp_t *request,
 283                                          const char *resource, int infile,
 284                                          int outfile) _CUPS_API_1_3;
 285 extern char             *cupsGetServerPPD(http_t *http, const char *name) _CUPS_API_1_3;
 286 extern int              cupsRemoveDest(const char *name,
 287                                        const char *instance,
 288                                        int num_dests, cups_dest_t **dests) _CUPS_API_1_3;
 289 extern void             cupsSetDefaultDest(const char *name,
 290                                            const char *instance,
 291                                            int num_dests,
 292                                            cups_dest_t *dests) _CUPS_API_1_3;
 293
 294 /**** New in CUPS 1.4/Mac OS X 10.6 ****/
 295 extern ipp_status_t     cupsCancelJob2(http_t *http, const char *name,
 296                                        int job_id, int purge) _CUPS_API_1_4;
 297 extern int              cupsCreateJob(http_t *http, const char *name,
 298                                       const char *title, int num_options,
 299                                       cups_option_t *options) _CUPS_API_1_4;
 300 extern ipp_status_t     cupsFinishDocument(http_t *http,
 301                                            const char *name) _CUPS_API_1_4;
 302 extern ipp_status_t     cupsGetDevices(http_t *http, int timeout,
 303                                        const char *include_schemes,
 304                                        const char *exclude_schemes,
 305                                        cups_device_cb_t callback,
 306                                        void *user_data) _CUPS_API_1_4;
 307 extern cups_dest_t      *cupsGetNamedDest(http_t *http, const char *name,
 308                                           const char *instance) _CUPS_API_1_4;
 309 extern const char       *cupsGetPassword2(const char *prompt, http_t *http,
 310                                           const char *method,
 311                                           const char *resource) _CUPS_API_1_4;
 312 extern http_status_t    cupsGetPPD3(http_t *http, const char *name,
 313                                     time_t *modtime, char *buffer,
 314                                     size_t bufsize) _CUPS_API_1_4;
 315 extern ipp_t            *cupsGetResponse(http_t *http,
 316                                          const char *resource) _CUPS_API_1_4;
 317 extern ssize_t          cupsReadResponseData(http_t *http, char *buffer,
 318                                              size_t length) _CUPS_API_1_4;
 319 extern http_status_t    cupsSendRequest(http_t *http, ipp_t *request,
 320                                         const char *resource,
 321                                         size_t length) _CUPS_API_1_4;
 322 extern void             cupsSetPasswordCB2(cups_password_cb2_t cb,
 323                                            void *user_data) _CUPS_API_1_4;
 324 extern http_status_t    cupsStartDocument(http_t *http, const char *name,
 325                                           int job_id, const char *docname,
 326                                           const char *format,
 327                                           int last_document) _CUPS_API_1_4;
 328 extern http_status_t    cupsWriteRequestData(http_t *http, const char *buffer,
 329                                              size_t length) _CUPS_API_1_4;
 330
 331 /**** New in CUPS 1.5 ****/
 332 extern void             cupsSetClientCertCB(cups_client_cert_cb_t cb,
 333                                             void *user_data) _CUPS_API_1_5;
 334 extern int              cupsSetCredentials(cups_array_t *certs) _CUPS_API_1_5;
 335 extern void             cupsSetServerCertCB(cups_server_cert_cb_t cb,
 336                                             void *user_data) _CUPS_API_1_5;
 337
 338 /**** New in CUPS 1.6 ****/
 339 extern http_t           *cupsConnectDest(cups_dest_t *dest);
 340 extern int              cupsEnumDests(cups_dest_cb_t cb, void *user_data) _CUPS_API_1_6;
 341 #  ifdef __BLOCKS__
 342 extern int              cupsEnumDestsBlock(cups_dest_block_t block) _CUPS_API_1_6;
 343 #  endif /* __BLOCKS__ */
 344
 345 #  ifdef __cplusplus
 346 }
 347 #  endif /* __cplusplus */
 348
 349 #endif /* !_CUPS_CUPS_H_ */
 350
 351 /*
 352  * End of "$Id: cups.h 8781 2009-08-28 17:34:54Z mike $".
 353  */