/*
* 'cupsCancelJob()' - Cancel a print job on the default server.
*
- * Use the cupsLastError() and cupsLastErrorString() functions to get
+ * Pass @code CUPS_JOBID_ALL@ to cancel all jobs or @code CUPS_JOBID_CURRENT@
+ * to cancel the current job on the named destination.
+ *
+ * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get
* the cause of any failure.
*/
cupsCancelJob(const char *name, /* I - Name of printer or class */
int job_id) /* I - Job ID */
{
- return (cupsCancelJob2(CUPS_HTTP_DEFAULT, job_id, 0)
+ return (cupsCancelJob2(CUPS_HTTP_DEFAULT, name, job_id, 0)
< IPP_REDIRECTION_OTHER_SITE);
}
* Canceled jobs remain in the job history while purged jobs are removed
* from the job history.
*
- * Use the cupsLastError() and cupsLastErrorString() functions to get
+ * Pass @code CUPS_JOBID_ALL@ to cancel all jobs or @code CUPS_JOBID_CURRENT@
+ * to cancel the current job on the named destination.
+ *
+ * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get
* the cause of any failure.
*
* @since CUPS 1.4@
*/
ipp_status_t /* O - IPP status */
-cupsCancelJob2(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
- int job_id, /* I - Job ID */
- int purge) /* I - 1 to purge, 0 to cancel */
+cupsCancelJob2(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
+ const char *name, /* I - Name of printer or class */
+ int job_id, /* I - Job ID or 0 for the current job, -1 for all jobs */
+ int purge) /* I - 1 to purge, 0 to cancel */
{
- char uri[HTTP_MAX_URI]; /* Job URI */
+ char uri[HTTP_MAX_URI]; /* Job/printer URI */
ipp_t *request; /* IPP request */
* Range check input...
*/
- if (job_id <= 0)
+ if (job_id < -1 || (!name && job_id == 0))
{
_cupsSetError(IPP_INTERNAL_ERROR, strerror(EINVAL));
return (0);
return (IPP_SERVICE_UNAVAILABLE);
/*
- * Build an IPP_CANCEL_JOB request, which requires the following
+ * Build an IPP_CANCEL_JOB or IPP_PURGE_JOBS request, which requires the following
* attributes:
*
* attributes-charset
* attributes-natural-language
- * job-uri
+ * job-uri or printer-uri + job-id
* requesting-user-name
- * [purge-job]
+ * [purge-job] or [purge-jobs]
*/
- request = ippNewRequest(IPP_CANCEL_JOB);
+ request = ippNewRequest(job_id < 0 ? IPP_PURGE_JOBS : IPP_CANCEL_JOB);
- snprintf(uri, sizeof(uri), "ipp://localhost/jobs/%d", job_id);
+ if (name)
+ {
+ httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL,
+ "localhost", ippPort(), "/printers/%s", name);
+
+ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL,
+ uri);
+ ippAddInteger(request, IPP_TAG_OPERATION, IPP_TAG_INTEGER, "job-id",
+ job_id);
+ }
+ else if (job_id > 0)
+ {
+ snprintf(uri, sizeof(uri), "ipp://localhost/jobs/%d", job_id);
+
+ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "job-uri", NULL, uri);
+ }
- ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "job-uri", NULL, uri);
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
NULL, cupsUser());
- if (purge)
+
+ if (purge && job_id >= 0)
ippAddBoolean(request, IPP_TAG_OPERATION, "purge-job", 1);
+ else if (!purge && job_id < 0)
+ ippAddBoolean(request, IPP_TAG_OPERATION, "purge-jobs", 0);
/*
* Do the request...
/*
* 'cupsCreateJob()' - Create an empty job.
*
- * Submit files for printing to the job using the cupsStartDocument(),
- * cupsWriteRequestData(), and cupsFinishDocument() functions.
+ * Submit files for printing to the job using the @link cupsStartDocument@,
+ * @link cupsWriteRequestData@, and @link cupsFinishDocument@ functions.
*
* @since CUPS 1.4@
*/
int /* O - Job ID or 0 on error */
cupsCreateJob(
- http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+ http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name, /* I - Printer or class name */
const char *title, /* I - Title of job */
int num_options, /* I - Number of options */
/*
* 'cupsFinishDocument()' - Finish sending a document.
*
+ * The document must have been started using @link cupsStartDocument@.
+ *
* @since CUPS 1.4@
*/
ipp_status_t /* O - Status of document submission */
-cupsFinishDocument(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsFinishDocument(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name) /* I - Printer or class name */
{
char resource[1024]; /* Printer resource */
/*
* 'cupsGetClasses()' - Get a list of printer classes from the default server.
*
- * This function is deprecated - use cupsGetDests() instead.
+ * This function is deprecated - use @link cupsGetDests@ instead.
*
* @deprecated@
*/
* This function returns the default printer or class as defined by
* the LPDEST or PRINTER environment variables. If these environment
* variables are not set, the server default destination is returned.
- * Applications should use the cupsGetDests() and cupsGetDest() functions
- * to get the user-defined default printer, as this function does not
- * support the lpoptions-defined default printer.
+ * Applications should use the @link cupsGetDests@ and @link cupsGetDest@
+ * functions to get the user-defined default printer, as this function does
+ * not support the lpoptions-defined default printer.
*/
-const char * /* O - Default printer or NULL */
+const char * /* O - Default printer or @code NULL@ */
cupsGetDefault(void)
{
/*
* This function returns the default printer or class as defined by
* the LPDEST or PRINTER environment variables. If these environment
* variables are not set, the server default destination is returned.
- * Applications should use the cupsGetDests() and cupsGetDest() functions
- * to get the user-defined default printer, as this function does not
- * support the lpoptions-defined default printer.
+ * Applications should use the @link cupsGetDests@ and @link cupsGetDest@
+ * functions to get the user-defined default printer, as this function does
+ * not support the lpoptions-defined default printer.
*
* @since CUPS 1.1.21@
*/
-const char * /* O - Default printer or NULL */
-cupsGetDefault2(http_t *http) /* I - HTTP connection */
+const char * /* O - Default printer or @code NULL@ */
+cupsGetDefault2(http_t *http) /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
{
ipp_t *request, /* IPP Request */
*response; /* IPP Response */
/*
* 'cupsGetJobs()' - Get the jobs from the default server.
+ *
+ * A "whichjobs" value of @code CUPS_WHICHJOBS_ALL@ returns all jobs regardless
+ * of state, while @code CUPS_WHICHJOBS_ACTIVE@ returns jobs that are
+ * pending, processing, or held and @code CUPS_WHICHJOBS_COMPLETED@ returns
+ * jobs that are stopped, canceled, aborted, or completed.
*/
int /* O - Number of jobs */
cupsGetJobs(cups_job_t **jobs, /* O - Job data */
- const char *mydest, /* I - NULL = all destinations, *
- * otherwise show jobs for mydest */
+ const char *name, /* I - @code NULL@ = all destinations, otherwise show jobs for mydest */
int myjobs, /* I - 0 = all users, 1 = mine */
- int completed) /* I - -1 = show all, 0 = active, *
- * 1 = completed jobs */
+ int whichjobs) /* I - @code CUPS_WHICHJOBS_ALL@, @code CUPS_WHICHJOBS_ACTIVE@, or @code CUPS_WHICHJOBS_COMPLETED@ */
{
/*
* Return the jobs...
*/
- return (cupsGetJobs2(CUPS_HTTP_DEFAULT, jobs, mydest, myjobs, completed));
+ return (cupsGetJobs2(CUPS_HTTP_DEFAULT, jobs, name, myjobs, whichjobs));
}
/*
* 'cupsGetJobs2()' - Get the jobs from the specified server.
*
+ * A "whichjobs" value of @code CUPS_WHICHJOBS_ALL@ returns all jobs regardless
+ * of state, while @code CUPS_WHICHJOBS_ACTIVE@ returns jobs that are
+ * pending, processing, or held and @code CUPS_WHICHJOBS_COMPLETED@ returns
+ * jobs that are stopped, canceled, aborted, or completed.
+ *
* @since CUPS 1.1.21@
*/
int /* O - Number of jobs */
-cupsGetJobs2(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetJobs2(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
cups_job_t **jobs, /* O - Job data */
- const char *mydest, /* I - NULL = all destinations, *
- * otherwise show jobs for mydest */
+ const char *name, /* I - @code NULL@ = all destinations, otherwise show jobs for mydest */
int myjobs, /* I - 0 = all users, 1 = mine */
- int completed) /* I - -1 = show all, 0 = active, *
- * 1 = completed jobs */
+ int whichjobs) /* I - @code CUPS_WHICHJOBS_ALL@, @code CUPS_WHICHJOBS_ACTIVE@, or @code CUPS_WHICHJOBS_COMPLETED@ */
{
int n; /* Number of jobs */
ipp_t *request, /* IPP Request */
* Get the right URI...
*/
- if (mydest)
+ if (name)
{
if (httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL,
- "localhost", 0, "/printers/%s", mydest) != HTTP_URI_OK)
+ "localhost", 0, "/printers/%s", name) != HTTP_URI_OK)
{
_cupsSetError(IPP_INTERNAL_ERROR, NULL);
if (myjobs)
ippAddBoolean(request, IPP_TAG_OPERATION, "my-jobs", 1);
- if (completed > 0)
+ if (whichjobs == CUPS_WHICHJOBS_COMPLETED)
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
"which-jobs", NULL, "completed");
- else if (completed < 0)
+ else if (whichjobs == CUPS_WHICHJOBS_ALL)
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
"which-jobs", NULL, "all");
/*
* 'cupsGetPPD()' - Get the PPD file for a printer on the default server.
*
- * For classes, cupsGetPPD() returns the PPD file for the first printer
+ * For classes, @code cupsGetPPD@ returns the PPD file for the first printer
* in the class.
*/
/*
* 'cupsGetPPD2()' - Get the PPD file for a printer from the specified server.
*
- * For classes, cupsGetPPD2() returns the PPD file for the first printer
+ * For classes, @code cupsGetPPD2@ returns the PPD file for the first printer
* in the class.
*
* @since CUPS 1.1.21@
*/
const char * /* O - Filename for PPD file */
-cupsGetPPD2(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetPPD2(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name) /* I - Printer name */
{
_cups_globals_t *cg = _cupsGlobals(); /* Pointer to library globals */
* the empty string, a new temporary file is created, otherwise the existing
* file will be overwritten as needed.
*
- * On success, HTTP_OK is returned for a new PPD file and HTTP_NOT_MODIFIED
- * if the existing PPD file is up-to-date. Any other status is an error.
+ * On success, @code HTTP_OK@ is returned for a new PPD file and
+ * @code HTTP_NOT_MODIFIED@ if the existing PPD file is up-to-date. Any other
+ * status is an error.
+ *
+ * For classes, @code cupsGetPPD3@ returns the PPD file for the first printer
+ * in the class.
*/
http_status_t /* O - HTTP status */
-cupsGetPPD3(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetPPD3(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name, /* I - Printer name */
time_t *modtime, /* IO - Modification time */
char *buffer, /* I - Filename buffer */
/*
* 'cupsGetPrinters()' - Get a list of printers from the default server.
*
- * This function is deprecated - use cupsGetDests() instead.
+ * This function is deprecated - use @link cupsGetDests@ instead.
*
* @deprecated@
*/
* 'cupsGetServerPPD()' - Get an available PPD file from the server.
*
* This function returns the named PPD file from the server. The
- * list of available PPDs is provided by the IPP CUPS_GET_PPDS
+ * list of available PPDs is provided by the IPP @code CUPS_GET_PPDS@
* operation.
*
* You must remove (unlink) the PPD file when you are finished with
* it. The PPD filename is stored in a static location that will be
- * overwritten on the next call to cupsGetPPD(), cupsGetPPD2(), or
- * cupsGetServerPPD().
+ * overwritten on the next call to @link cupsGetPPD@, @link cupsGetPPD2@,
+ * or @link cupsGetServerPPD@.
*
* @since CUPS 1.3@
*/
-char * /* O - Name of PPD file or NULL on error */
-cupsGetServerPPD(http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+char * /* O - Name of PPD file or @code NULL@ on error */
+cupsGetServerPPD(http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name) /* I - Name of PPD file ("ppd-name") */
{
int fd; /* PPD file descriptor */
* 'cupsPrintFile()' - Print a file to a printer or class on the default server.
*/
-int /* O - Job ID */
+int /* O - Job ID or 0 on error */
cupsPrintFile(const char *name, /* I - Printer or class name */
const char *filename, /* I - File to print */
const char *title, /* I - Title of job */
/*
- * 'cupsPrintFile2()' - Print a file to a printer or class on the specified server.
+ * 'cupsPrintFile2()' - Print a file to a printer or class on the specified
+ * server.
*
* @since CUPS 1.1.21@
*/
-int /* O - Job ID */
+int /* O - Job ID or 0 on error */
cupsPrintFile2(
http_t *http, /* I - HTTP connection */
const char *name, /* I - Printer or class name */
* default server.
*/
-int /* O - Job ID */
+int /* O - Job ID or 0 on error */
cupsPrintFiles(
const char *name, /* I - Printer or class name */
int num_files, /* I - Number of files */
* @since CUPS 1.1.21@
*/
-int /* O - Job ID */
+int /* O - Job ID or 0 on error */
cupsPrintFiles2(
- http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+ http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name, /* I - Printer or class name */
int num_files, /* I - Number of files */
const char **files, /* I - File(s) to print */
* Unable to open print file, cancel the job and return...
*/
- cupsCancelJob2(http, job_id, 0);
+ cupsCancelJob2(http, name, job_id, 0);
return (0);
}
* Unable to queue, cancel the job and return...
*/
- cupsCancelJob2(http, job_id, 0);
+ cupsCancelJob2(http, name, job_id, 0);
return (0);
}
}
/*
* 'cupsStartDocument()' - Add a document to a job created with cupsCreateJob().
*
- * Use cupsWriteRequestData() to write data for the document and
- * cupsFinishDocument() to finish the document and get the submission status.
+ * Use @link cupsWriteRequestData@ to write data for the document and
+ * @link cupsFinishDocument@ to finish the document and get the submission status.
*
- * The MIME type constants CUPS_FORMAT_AUTO, CUPS_FORMAT_PDF,
- * CUPS_FORMAT_POSTSCRIPT, CUPS_FORMAT_RAW, and CUPS_FORMAT_TEXT are provided
- * for the "format" argument, although any supported MIME type string can be
- * supplied.
+ * The MIME type constants @code CUPS_FORMAT_AUTO@, @code CUPS_FORMAT_PDF@,
+ * @code CUPS_FORMAT_POSTSCRIPT@, @code CUPS_FORMAT_RAW@, and
+ * @code CUPS_FORMAT_TEXT@ are provided for the "format" argument, although
+ * any supported MIME type string can be supplied.
*
* @since CUPS 1.4@
*/
http_status_t /* O - HTTP status of request */
cupsStartDocument(
- http_t *http, /* I - HTTP connection or CUPS_HTTP_DEFAULT */
+ http_t *http, /* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
const char *name, /* I - Printer or class name */
- int job_id, /* I - Job ID from cupsCreateJob() */
+ int job_id, /* I - Job ID from @link cupsCreateJob@ */
const char *docname, /* I - Name of document */
- const char *format, /* I - MIME type or CUPS_FORMAT_foo */
+ const char *format, /* I - MIME type or @code CUPS_FORMAT_foo@ */
int last_document) /* I - 1 for last document in job, 0 otherwise */
{
char resource[1024], /* Resource for destinatio */
projects / thirdparty / cups.git / blobdiff