Lines Matching +full:argument +full:- +full:count
1 ---
4 copyright: Copyright © 2007-2022 by Apple Inc. All Rights Reserved.
30 - Do not use undocumented or deprecated APIs,
31 - Do not rely on pre-configured printers,
32 - Do not assume that printers support specific features or formats, and
33 - Do not rely on implementation details (PPDs, etc.)
38 copies, two-sided on A4 media, and staple each copy") and have the printing
78 if (dest->instance)
79 printf("%s/%s\n", dest->name, dest->instance);
81 puts(dest->name);
103 library, and then double-click on `libcups.tbd`.
111 From the command-line, create a file called `simple.c` using your favorite
115 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
118 The `cups-config` command provides the compiler flags (`cups-config --cflags`)
119 and libraries (`cups-config --libs`) needed for the local system.
145 The `flags` argument specifies enumeration options, which at present must be
148 The `msec` argument specifies the maximum amount of time that should be used for
149 enumeration in milliseconds - interactive applications should keep this value to
152 The `cancel` argument points to an integer variable that, when set to a non-zero
158 "printer-type" value is masked by the `mask` value and compared to the `type`
160 hosted on the local system, pass `CUPS_PRINTER_LOCAL` for the `type` argument
161 and `CUPS_PRINTER_DISCOVERED` for the `mask` argument. The following constants
164 - `CUPS_PRINTER_CLASS`: A collection of destinations.
165 - `CUPS_PRINTER_FAX`: A facsimile device.
166 - `CUPS_PRINTER_LOCAL`: A local printer or class. This constant has the value 0
167 (no bits set) and is only used for the `type` argument and is paired with the
169 `mask` argument.
170 - `CUPS_PRINTER_REMOTE`: A remote (shared) printer or class.
171 - `CUPS_PRINTER_DISCOVERED`: An available network printer or class.
172 - `CUPS_PRINTER_BW`: Can do B&W printing.
173 - `CUPS_PRINTER_COLOR`: Can do color printing.
174 - `CUPS_PRINTER_DUPLEX`: Can do two-sided printing.
175 - `CUPS_PRINTER_STAPLE`: Can staple output.
176 - `CUPS_PRINTER_COLLATE`: Can quickly collate copies.
177 - `CUPS_PRINTER_PUNCH`: Can punch output.
178 - `CUPS_PRINTER_COVER`: Can cover output.
179 - `CUPS_PRINTER_BIND`: Can bind output.
180 - `CUPS_PRINTER_SORT`: Can sort output (mailboxes, etc.)
181 - `CUPS_PRINTER_SMALL`: Can print on Letter/Legal/A4-size media.
182 - `CUPS_PRINTER_MEDIUM`: Can print on Tabloid/B/C/A3/A2-size media.
183 - `CUPS_PRINTER_LARGE`: Can print on D/E/A1/A0-size media.
184 - `CUPS_PRINTER_VARIABLE`: Can print on rolls and custom-size media.
186 The `cb` argument specifies a function to call for every destination that is
193 The callback function receives a copy of the `user_data` argument along with a
194 bitfield \(`flags`) and the destination that was found. The `flags` argument
197 - `CUPS_DEST_FLAGS_MORE`: There are more destinations coming.
198 - `CUPS_DEST_FLAGS_REMOVED`: The destination has gone away and should be removed
200 - `CUPS_DEST_FLAGS_ERROR`: An error occurred. The reason for the error can be
230 user_data->num_dests =
231 cupsRemoveDest(dest->name, dest->instance,
232 user_data->num_dests,
233 &(user_data->dests));
241 user_data->num_dests =
242 cupsCopyDest(dest, user_data->num_dests,
243 &(user_data->dests));
288 - "auth-info-required": The type of authentication required for printing to this
291 - "printer-info": The human-readable description of the destination such as "My
293 - "printer-is-accepting-jobs": "true" if the destination is accepting new jobs,
295 - "printer-is-shared": "true" if the destination is being shared with other
297 - "printer-location": The human-readable location of the destination such as
299 - "printer-make-and-model": The human-readable make and model of the destination
301 - "printer-state": "3" if the destination is idle, "4" if the destination is
303 - "printer-state-change-time": The UNIX time when the destination entered the
305 - "printer-state-reasons": Additional comma-delimited state keywords for the
306 destination such as "media-tray-empty-error" and "toner-low-warning".
307 - "printer-type": The `cups_ptype_t` value associated with the destination.
308 - "printer-uri-supported": The URI associated with the destination; if not set,
314 const char *model = cupsGetOption("printer-make-and-model",
315 dest->num_options,
316 dest->options);
327 The `http` argument specifies a connection to the CUPS scheduler and is
328 typically the constant `CUPS_HTTP_DEFAULT`. The `dest` argument specifies the
348 The `option` argument specifies the name of the option to check. The following
351 - `CUPS_COPIES`: Controls the number of copies that are produced.
352 - `CUPS_FINISHINGS`: A comma-delimited list of integer constants that control
355 - `CUPS_MEDIA`: Controls the media size that is used, typically one of the
361 - `CUPS_MEDIA_SOURCE`: Controls where the media is pulled from, typically either
363 - `CUPS_MEDIA_TYPE`: Controls the type of media that is used, typically one of
369 - `CUPS_NUMBER_UP`: Controls the number of document pages that are placed on
371 - `CUPS_ORIENTATION`: Controls the orientation of document pages placed on the
373 - `CUPS_PRINT_COLOR_MODE`: Controls whether the output is in color
377 - `CUPS_PRINT_QUALITY`: Controls the generate quality of the output:
380 - `CUPS_SIDES`: Controls whether prints are placed on one or both sides of the
384 If the `value` argument is `NULL`, the `cupsCheckDestSupported` function returns
408 int i, count = ippGetCount(finishings);
411 for (i = 0; i < count; i ++)
417 The "job-creation-attributes" option can be queried to get a list of supported
423 "job-creation-attributes");
424 int i, count = ippGetCount(attrs);
426 for (i = 0; i < count; i ++)
432 There are two sets of default values - user defaults that are available via the
448 cupsGetOption(CUPS_FINISHINGS, dest->num_options,
449 dest->options);
460 int i, count = ippGetCount(def_attr);
464 for (i = 1; i < count; i ++)
474 but be out of staples - the supported values will list both punch and staple
477 have a single size loaded at any given time - the ready values are limited to
495 int i, count = ippGetCount(ready_finishings);
498 for (i = 0; i < count; i ++)
540 `flags` argument specifies a bitfield controlling various lookup options:
542 - `CUPS_MEDIA_FLAGS_DEFAULT`: Find the closest size supported by the printer.
543 - `CUPS_MEDIA_FLAGS_BORDERLESS`: Find a borderless size.
544 - `CUPS_MEDIA_FLAGS_DUPLEX`: Find a size compatible with two-sided printing.
545 - `CUPS_MEDIA_FLAGS_EXACT`: Find an exact match for the size.
546 - `CUPS_MEDIA_FLAGS_READY`: If the printer supports media sensing or
551 in the structure pointed to by the `size` argument and 1 is returned. Otherwise
554 For example, the following code prints the margins for two-sided printing on US
589 int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
593 for (i = 0; i < count; i ++)
619 CUPS provides three functions to get localized, human-readable strings in the
650 The `title` argument specifies a name for the print job such as "My Document".
655 to by the `job_id` argument and `IPP_STATUS_OK` is returned. Otherwise, an IPP
659 two-sided US Letter document:
702 The `docname` argument specifies the name of the document, typically the
703 original filename. The `format` argument specifies the MIME media type of the
706 - `CUPS_FORMAT_JPEG`: "image/jpeg"
707 - `CUPS_FORMAT_PDF`: "application/pdf"
708 - `CUPS_FORMAT_POSTSCRIPT`: "application/postscript"
709 - `CUPS_FORMAT_TEXT`: "text/plain"
711 The `num_options` and `options` arguments specify per-document print options,
712 which at present must be 0 and `NULL`. The `last_document` argument specifies
761 The `dest` argument specifies the destination to connect to.
763 The `flags` argument specifies whether you want to connect to the scheduler
767 The `msec` argument specifies how long you are willing to wait for the
768 connection to be established in milliseconds. Specify a value of `-1` to wait
771 The `cancel` argument specifies the address of an integer variable that can be
772 set to a non-zero value to cancel the connection. Specify a value of `NULL`
799 `IPP_OP_GET_PRINTER_ATTRIBUTES`, etc.) and a 32-bit integer identifier.
806 The `op` argument specifies the IPP operation code for the request. For
807 example, the following code creates an IPP Get-Printer-Attributes request:
814 Each IPP request starts with two IPP attributes, "attributes-charset" and
815 "attributes-natural-language", followed by IPP attribute(s) that specify the
817 "attributes-charset" and "attributes-natural-language" attributes, but you must
819 "printer-uri" attribute to the IPP Get-Printer-Attributes request to specify
822 const char *printer_uri = cupsGetOption("device-uri",
823 dest->num_options,
824 dest->options);
827 "printer-uri", NULL, printer_uri);
832 > up the "printer-uri-supported" option instead of the "device-uri" value.
834 The `ippAddString` function adds the "printer-uri" attribute the the IPP
835 request. The `IPP_TAG_OPERATION` argument specifies that the attribute is part
836 of the operation. The `IPP_TAG_URI` argument specifies that the value is a
837 Universal Resource Identifier (URI) string. The `NULL` argument specifies there
839 the `printer_uri` argument specifies the string value.
841 The IPP Get-Printer-Attributes request also supports an IPP attribute called
842 "requested-attributes" that lists the attributes and values you are interested
847 "printer-state",
848 "printer-state-message",
849 "printer-state-reasons"
853 "requested-attributes", 3, NULL,
857 case three. The `IPP_TAG_KEYWORD` argument specifies that the strings are
864 - `ippAddBoolean` adds a boolean (`IPP_TAG_BOOLEAN`) attribute with one value.
865 - `ippAddInteger` adds an enum (`IPP_TAG_ENUM`) or integer (`IPP_TAG_INTEGER`)
867 - `ippAddIntegers` adds an enum or integer attribute with one or more values.
868 - `ippAddOctetString` adds an octetString attribute with one value.
869 - `ippAddOutOfBand` adds a admin-defined (`IPP_TAG_ADMINDEFINE`), default
870 (`IPP_TAG_DEFAULT`), delete-attribute (`IPP_TAG_DELETEATTR`), no-value
871 (`IPP_TAG_NOVALUE`), not-settable (`IPP_TAG_NOTSETTABLE`), unknown
872 (`IPP_TAG_UNKNOWN`), or unsupported (`IPP_TAG_UNSUPPORTED_VALUE`) out-of-band
874 - `ippAddRange` adds a rangeOfInteger attribute with one range.
875 - `ippAddRanges` adds a rangeOfInteger attribute with one or more ranges.
876 - `ippAddResolution` adds a resolution attribute with one resolution.
877 - `ippAddResolutions` adds a resolution attribute with one or more resolutions.
878 - `ippAddString` adds a charset (`IPP_TAG_CHARSET`), keyword (`IPP_TAG_KEYWORD`),
883 - `ippAddStrings` adds a charset, keyword, mimeMediaType, name, naturalLanguage,
891 Get-Printer-Attributes request to the destination and saves the response:
895 For requests like Send-Document that include a file, the `cupsDoFileRequest`
913 A human-readable error message is also available using the `cupsLastErrorString`
927 `IPP_STATUS_ERROR_BAD_REQUEST`, etc.) and the corresponding 32-bit integer
935 if ((attr = ippFindAttribute(response, "printer-state",
938 printf("printer-state=%s\n",
939 ippEnumString("printer-state", ippGetInteger(attr, 0)));
942 puts("printer-state=unknown");
944 if ((attr = ippFindAttribute(response, "printer-state-message",
947 printf("printer-state-message=\"%s\"\n",
951 if ((attr = ippFindAttribute(response, "printer-state-reasons",
954 int i, count = ippGetCount(attr);
956 puts("printer-state-reasons=");
957 for (i = 0; i < count; i ++)
991 The `prompt` argument is a string from CUPS that should be displayed to the
994 The `http` argument is the connection hosting the request that is being
999 The `method` argument specifies the HTTP method used for the request and is
1002 The `resource` argument specifies the path used for the request.
1004 The `user_data` argument provides the user data pointer from the