cups/cups.h

   1 /*
   2  * "$Id: cups.h 5138 2006-02-21 10:49:06Z mike $"
   3  *
   4  *   API definitions for the Common UNIX Printing System (CUPS).
   5  *
   6  *   Copyright 1997-2006 by Easy Software Products.
   7  *
   8  *   These coded instructions, statements, and computer programs are the
   9  *   property of Easy Software Products and are protected by Federal
  10  *   copyright law.  Distribution and use rights are outlined in the file
  11  *   "LICENSE.txt" which should have been included with this file.  If this
  12  *   file is missing or damaged please contact Easy Software Products
  13  *   at:
  14  *
  15  *       Attn: CUPS Licensing Information
  16  *       Easy Software Products
  17  *       44141 Airport View Drive, Suite 204
  18  *       Hollywood, Maryland 20636 USA
  19  *
  20  *       Voice: (301) 373-9600
  21  *       EMail: cups-info@cups.org
  22  *         WWW: http://www.cups.org
  23  *
  24  *   This file is subject to the Apple OS-Developed Software exception.
  25  */
  26
  27 #ifndef _CUPS_CUPS_H_
  28 #  define _CUPS_CUPS_H_
  29
  30 /*
  31  * Include necessary headers...
  32  */
  33
  34 #  include "ipp.h"
  35 #  include "ppd.h"
  36 #  include "language.h"
  37
  38
  39 /*
  40  * With GCC 3.0 and higher, we can mark old APIs "deprecated" so you get
  41  * a warning at compile-time.
  42  */
  43
  44 #  if defined(__GNUC__) && __GNUC__ > 2
  45 #    define _CUPS_DEPRECATED __attribute__ ((__deprecated__))
  46 #  else
  47 #    define _CUPS_DEPRECATED
  48 #  endif /* __GNUC__ && __GNUC__ > 2 */
  49
  50
  51 /*
  52  * C++ magic...
  53  */
  54
  55 #  ifdef __cplusplus
  56 extern "C" {
  57 #  endif /* __cplusplus */
  58
  59
  60 /*
  61  * Constants...
  62  */
  63
  64 #  define CUPS_VERSION          1.0190
  65 #  define CUPS_VERSION_MAJOR    1
  66 #  define CUPS_VERSION_MINOR    2
  67 #  define CUPS_VERSION_PATCH    -10
  68 #  define CUPS_DATE_ANY         -1
  69
  70
  71 /*
  72  * Types and structures...
  73  */
  74
  75 typedef unsigned cups_ptype_t;          /**** Printer Type/Capability Bits ****/
  76 enum cups_ptype_e                       /* Not a typedef'd enum so we can OR */
  77 {
  78   CUPS_PRINTER_LOCAL = 0x0000,          /* Local printer or class */
  79   CUPS_PRINTER_CLASS = 0x0001,          /* Printer class */
  80   CUPS_PRINTER_REMOTE = 0x0002,         /* Remote printer or class */
  81   CUPS_PRINTER_BW = 0x0004,             /* Can do B&W printing */
  82   CUPS_PRINTER_COLOR = 0x0008,          /* Can do color printing */
  83   CUPS_PRINTER_DUPLEX = 0x0010,         /* Can do duplexing */
  84   CUPS_PRINTER_STAPLE = 0x0020,         /* Can staple output */
  85   CUPS_PRINTER_COPIES = 0x0040,         /* Can do copies */
  86   CUPS_PRINTER_COLLATE = 0x0080,        /* Can collage copies */
  87   CUPS_PRINTER_PUNCH = 0x0100,          /* Can punch output */
  88   CUPS_PRINTER_COVER = 0x0200,          /* Can cover output */
  89   CUPS_PRINTER_BIND = 0x0400,           /* Can bind output */
  90   CUPS_PRINTER_SORT = 0x0800,           /* Can sort output */
  91   CUPS_PRINTER_SMALL = 0x1000,          /* Can do Letter/Legal/A4 */
  92   CUPS_PRINTER_MEDIUM = 0x2000,         /* Can do Tabloid/B/C/A3/A2 */
  93   CUPS_PRINTER_LARGE = 0x4000,          /* Can do D/E/A1/A0 */
  94   CUPS_PRINTER_VARIABLE = 0x8000,       /* Can do variable sizes */
  95   CUPS_PRINTER_IMPLICIT = 0x10000,      /* Implicit class */
  96   CUPS_PRINTER_DEFAULT = 0x20000,       /* Default printer on network */
  97   CUPS_PRINTER_FAX = 0x40000,           /* Fax queue */
  98   CUPS_PRINTER_REJECTING = 0x80000,     /* Printer is rejecting jobs */
  99   CUPS_PRINTER_DELETE = 0x100000,       /* Delete printer @since CUPS 1.2@ */
 100   CUPS_PRINTER_NOT_SHARED = 0x200000,   /* Printer is not shared @since CUPS 1.2@ */
 101   CUPS_PRINTER_AUTHENTICATED = 0x400000,/* Printer requires authentication @since CUPS 1.2@ */
 102   CUPS_PRINTER_OPTIONS = 0x66fffc       /* ~(CLASS | REMOTE | IMPLICIT) */
 103 };
 104
 105 typedef const char *(*cups_password_cb_t)(const char *);
 106                                         /**** Password callback ****/
 107
 108 typedef struct cups_option_s            /**** Printer Options ****/
 109 {
 110   char          *name;                  /* Name of option */
 111   char          *value;                 /* Value of option */
 112 } cups_option_t;
 113
 114 typedef struct cups_dest_s              /**** Destination ****/
 115 {
 116   char          *name,                  /* Printer or class name */
 117                 *instance;              /* Local instance name or NULL */
 118   int           is_default;             /* Is this printer the default? */
 119   int           num_options;            /* Number of options */
 120   cups_option_t *options;               /* Options */
 121 } cups_dest_t;
 122
 123 typedef struct cups_job_s               /**** Job ****/
 124 {
 125   int           id;                     /* The job ID */
 126   char          *dest;                  /* Printer or class name */
 127   char          *title;                 /* Title/job name */
 128   char          *user;                  /* User the submitted the job */
 129   char          *format;                /* Document format */
 130   ipp_jstate_t  state;                  /* Job state */
 131   int           size;                   /* Size in kilobytes */
 132   int           priority;               /* Priority (1-100) */
 133   time_t        completed_time;         /* Time the job was completed */
 134   time_t        creation_time;          /* Time the job was created */
 135   time_t        processing_time;        /* Time the job was processed */
 136 } cups_job_t;
 137
 138
 139 /*
 140  * Functions...
 141  */
 142
 143 extern int              cupsCancelJob(const char *printer, int job);
 144 extern ipp_t            *cupsDoFileRequest(http_t *http, ipp_t *request,
 145                                            const char *resource,
 146                                            const char *filename);
 147 extern ipp_t            *cupsDoRequest(http_t *http, ipp_t *request,
 148                                        const char *resource);
 149 extern http_encryption_t cupsEncryption(void);
 150 extern void             cupsFreeJobs(int num_jobs, cups_job_t *jobs);
 151 extern int              cupsGetClasses(char ***classes) _CUPS_DEPRECATED;
 152 extern const char       *cupsGetDefault(void);
 153 extern int              cupsGetJobs(cups_job_t **jobs, const char *dest,
 154                                     int myjobs, int completed);
 155 extern const char       *cupsGetPPD(const char *printer);
 156 extern int              cupsGetPrinters(char ***printers) _CUPS_DEPRECATED;
 157 extern ipp_status_t     cupsLastError(void);
 158 extern int              cupsPrintFile(const char *printer, const char *filename,
 159                                       const char *title, int num_options,
 160                                       cups_option_t *options);
 161 extern int              cupsPrintFiles(const char *printer, int num_files,
 162                                        const char **files, const char *title,
 163                                        int num_options, cups_option_t *options);
 164 extern char             *cupsTempFile(char *filename, int len) _CUPS_DEPRECATED;
 165 extern int              cupsTempFd(char *filename, int len);
 166
 167 extern int              cupsAddDest(const char *name, const char *instance,
 168                                     int num_dests, cups_dest_t **dests);
 169 extern void             cupsFreeDests(int num_dests, cups_dest_t *dests);
 170 extern cups_dest_t      *cupsGetDest(const char *name, const char *instance,
 171                                      int num_dests, cups_dest_t *dests);
 172 extern int              cupsGetDests(cups_dest_t **dests);
 173 extern void             cupsSetDests(int num_dests, cups_dest_t *dests);
 174
 175 extern int              cupsAddOption(const char *name, const char *value,
 176                                       int num_options, cups_option_t **options);
 177 extern void             cupsEncodeOptions(ipp_t *ipp, int num_options,
 178                                           cups_option_t *options);
 179 extern void             cupsFreeOptions(int num_options, cups_option_t *options);
 180 extern const char       *cupsGetOption(const char *name, int num_options,
 181                                        cups_option_t *options);
 182 extern int              cupsParseOptions(const char *arg, int num_options,
 183                                          cups_option_t **options);
 184 extern int              cupsMarkOptions(ppd_file_t *ppd, int num_options,
 185                                         cups_option_t *options);
 186
 187 extern const char       *cupsGetPassword(const char *prompt);
 188 extern const char       *cupsServer(void);
 189 extern void             cupsSetEncryption(http_encryption_t e);
 190 extern void             cupsSetPasswordCB(cups_password_cb_t cb);
 191 extern void             cupsSetServer(const char *server);
 192 extern void             cupsSetUser(const char *user);
 193 extern const char       *cupsUser(void);
 194
 195 /**** New in CUPS 1.1.20 ****/
 196 extern int              cupsDoAuthentication(http_t *http, const char *method,
 197                                              const char *resource);
 198 extern http_status_t    cupsGetFile(http_t *http, const char *resource,
 199                                     const char *filename);
 200 extern http_status_t    cupsGetFd(http_t *http, const char *resource, int fd);
 201 extern http_status_t    cupsPutFile(http_t *http, const char *resource,
 202                                     const char *filename);
 203 extern http_status_t    cupsPutFd(http_t *http, const char *resource, int fd);
 204
 205 /**** New in CUPS 1.1.21 ****/
 206 extern const char       *cupsGetDefault2(http_t *http);
 207 extern int              cupsGetDests2(http_t *http, cups_dest_t **dests);
 208 extern int              cupsGetJobs2(http_t *http, cups_job_t **jobs,
 209                                      const char *dest, int myjobs,
 210                                      int completed);
 211 extern const char       *cupsGetPPD2(http_t *http, const char *printer);
 212 extern int              cupsPrintFile2(http_t *http, const char *printer,
 213                                        const char *filename,
 214                                        const char *title, int num_options,
 215                                        cups_option_t *options);
 216 extern int              cupsPrintFiles2(http_t *http, const char *printer,
 217                                         int num_files, const char **files,
 218                                         const char *title, int num_options,
 219                                         cups_option_t *options);
 220 extern int              cupsSetDests2(http_t *http, int num_dests,
 221                                       cups_dest_t *dests);
 222
 223 /**** New in CUPS 1.2 ****/
 224 extern ssize_t          cupsBackChannelRead(char *buffer, size_t bytes,
 225                                             double timeout);
 226 extern ssize_t          cupsBackChannelWrite(const char *buffer, size_t bytes,
 227                                              double timeout);
 228 extern void             cupsEncodeOptions2(ipp_t *ipp, int num_options,
 229                                            cups_option_t *options,
 230                                            ipp_tag_t group_tag);
 231 extern const char       *cupsLastErrorString(void);
 232 extern char             *cupsNotifySubject(cups_lang_t *lang, ipp_t *event);
 233 extern char             *cupsNotifyText(cups_lang_t *lang, ipp_t *event);
 234 extern cups_file_t      *cupsTempFile2(char *filename, int len);
 235
 236
 237 #  ifdef __cplusplus
 238 }
 239 #  endif /* __cplusplus */
 240
 241 #endif /* !_CUPS_CUPS_H_ */
 242
 243 /*
 244  * End of "$Id: cups.h 5138 2006-02-21 10:49:06Z mike $".
 245  */