/*
- * 'cupsConnectDest()' - Connect to the server for a destination.
+ * 'cupsConnectDest()' - Open a conection to the destination.
*
- * Connect to the destination, returning a new http_t connection object and
- * optionally the resource path to use for the destination. These calls will
- * block until a connection is made, the timeout expires, the integer pointed
- * to by "cancel" is non-zero, or the callback function (or block) returns 0,
- * The caller is responsible for calling httpClose() on the returned object.
+ * Connect to the destination, returning a new @code http_t@ connection object
+ * and optionally the resource path to use for the destination. These calls
+ * will block until a connection is made, the timeout expires, the integer
+ * pointed to by "cancel" is non-zero, or the callback function (or block)
+ * returns 0. The caller is responsible for calling @link httpClose@ on the
+ * returned connection.
*
* @since CUPS 1.6/macOS 10.8@
*/
-http_t * /* O - Connection to server or @code NULL@ */
+http_t * /* O - Connection to destination or @code NULL@ */
cupsConnectDest(
cups_dest_t *dest, /* I - Destination */
unsigned flags, /* I - Connection flags */
#ifdef __BLOCKS__
/*
- * 'cupsConnectDestBlock()' - Connect to the server for a destination.
+ * 'cupsConnectDestBlock()' - Open a connection to the destination.
*
- * Connect to the destination, returning a new http_t connection object and
- * optionally the resource path to use for the destination. These calls will
- * block until a connection is made, the timeout expires, the integer pointed
- * to by "cancel" is non-zero, or the callback function (or block) returns 0,
- * The caller is responsible for calling httpClose() on the returned object.
+ * Connect to the destination, returning a new @code http_t@ connection object
+ * and optionally the resource path to use for the destination. These calls
+ * will block until a connection is made, the timeout expires, the integer
+ * pointed to by "cancel" is non-zero, or the block returns 0. The caller is
+ * responsible for calling @link httpClose@ on the returned connection.
*
- * @since CUPS 1.6/macOS 10.8@
+ * @since CUPS 1.6/macOS 10.8@ @exclude all@
*/
-http_t * /* O - Connection to server or @code NULL@ */
+http_t * /* O - Connection to destination or @code NULL@ */
cupsConnectDestBlock(
cups_dest_t *dest, /* I - Destination */
unsigned flags, /* I - Connection flags */
/*
* 'cupsEnumDests()' - Enumerate available destinations with a callback function.
*
- * Destinations are enumerated from one or more sources. The callback function
- * receives the @code user_data@ pointer, destination name, instance, number of
- * options, and options which can be used as input to the @link cupsAddDest@
- * function. The function must return 1 to continue enumeration or 0 to stop.
+ * Destinations are enumerated from one or more sources. The callback function
+ * receives the @code user_data@ pointer and the destination pointer which can
+ * be used as input to the @link cupsCopyDest@ function. The function must
+ * return 1 to continue enumeration or 0 to stop.
+ *
+ * The @code type@ and @code mask@ arguments allow the caller to filter the
+ * destinations that are enumerated. Passing 0 for both will enumerate all
+ * printers. The constant @code CUPS_PRINTER_DISCOVERED@ is used to filter on
+ * destinations that are available but have not yet been added locally.
*
* Enumeration happens on the current thread and does not return until all
* destinations have been enumerated or the callback function returns 0.
*
+ * Note: The callback function will likely receive multiple updates for the same
+ * destinations - it is up to the caller to suppress any duplicate destinations.
+ *
* @since CUPS 1.6/macOS 10.8@
*/
return (0);
/*
- * Get the list of local printers and pass them to the callback function...
+ * Get ready to enumerate...
*/
- num_dests = _cupsGetDests(CUPS_HTTP_DEFAULT, IPP_OP_CUPS_GET_PRINTERS, NULL,
- &dests, type, mask | CUPS_PRINTER_3D);
-
- if ((user_default = _cupsUserDefault(name, sizeof(name))) != NULL)
- defprinter = name;
- else if ((defprinter = cupsGetDefault2(CUPS_HTTP_DEFAULT)) != NULL)
- {
- strlcpy(name, defprinter, sizeof(name));
- defprinter = name;
- }
-
- if (defprinter)
- {
- /*
- * Separate printer and instance name...
- */
-
- if ((instance = strchr(name, '/')) != NULL)
- *instance++ = '\0';
-
- /*
- * Lookup the printer and instance and make it the default...
- */
-
- if ((dest = cupsGetDest(name, instance, num_dests, dests)) != NULL)
- dest->is_default = 1;
- }
-
#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
data.type = type;
data.mask = mask;
data.devices = cupsArrayNew3((cups_array_func_t)cups_dnssd_compare_devices, NULL, NULL, 0, NULL, (cups_afree_func_t)cups_dnssd_free_device);
#endif /* HAVE_DNSSD || HAVE_AVAHI */
- for (i = num_dests, dest = dests;
- i > 0 && (!cancel || !*cancel);
- i --, dest ++)
+ if (!(mask & CUPS_PRINTER_DISCOVERED) || !(type & CUPS_PRINTER_DISCOVERED))
{
-#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
- const char *device_uri; /* Device URI */
-#endif /* HAVE_DNSSD || HAVE_AVAHI */
+ /*
+ * Get the list of local printers and pass them to the callback function...
+ */
- if (!(*cb)(user_data, i > 1 ? CUPS_DEST_FLAGS_MORE : CUPS_DEST_FLAGS_NONE,
- dest))
- break;
+ num_dests = _cupsGetDests(CUPS_HTTP_DEFAULT, IPP_OP_CUPS_GET_PRINTERS, NULL,
+ &dests, type, mask);
-#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
- if (!dest->instance && (device_uri = cupsGetOption("device-uri", dest->num_options, dest->options)) != NULL && !strncmp(device_uri, "dnssd://", 8))
+ if ((user_default = _cupsUserDefault(name, sizeof(name))) != NULL)
+ defprinter = name;
+ else if ((defprinter = cupsGetDefault2(CUPS_HTTP_DEFAULT)) != NULL)
+ {
+ strlcpy(name, defprinter, sizeof(name));
+ defprinter = name;
+ }
+
+ if (defprinter)
{
/*
- * Add existing queue using service name, etc. so we don't list it again...
+ * Separate printer and instance name...
*/
- char scheme[32], /* URI scheme */
- userpass[32], /* Username:password */
- serviceName[256], /* Service name (host field) */
- resource[256], /* Resource (options) */
- *regtype, /* Registration type */
- *replyDomain; /* Registration domain */
- int port; /* Port number (not used) */
-
- if (httpSeparateURI(HTTP_URI_CODING_ALL, device_uri, scheme, sizeof(scheme), userpass, sizeof(userpass), serviceName, sizeof(serviceName), &port, resource, sizeof(resource)) >= HTTP_URI_STATUS_OK)
- {
- if ((regtype = strstr(serviceName, "._ipp")) != NULL)
- {
- *regtype++ = '\0';
+ if ((instance = strchr(name, '/')) != NULL)
+ *instance++ = '\0';
- if ((replyDomain = strstr(regtype, "._tcp.")) != NULL)
- {
- replyDomain[5] = '\0';
- replyDomain += 6;
+ /*
+ * Lookup the printer and instance and make it the default...
+ */
- if ((device = cups_dnssd_get_device(&data, serviceName, regtype, replyDomain)) != NULL)
- device->state = _CUPS_DNSSD_ACTIVE;
- }
- }
- }
+ if ((dest = cupsGetDest(name, instance, num_dests, dests)) != NULL)
+ dest->is_default = 1;
}
+
+ for (i = num_dests, dest = dests;
+ i > 0 && (!cancel || !*cancel);
+ i --, dest ++)
+ {
+#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
+ const char *device_uri; /* Device URI */
#endif /* HAVE_DNSSD || HAVE_AVAHI */
- }
- cupsFreeDests(num_dests, dests);
+ if (!(*cb)(user_data, i > 1 ? CUPS_DEST_FLAGS_MORE : CUPS_DEST_FLAGS_NONE,
+ dest))
+ break;
- if (i > 0 || msec == 0)
- {
#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
- cupsArrayDelete(data.devices);
+ if (!dest->instance && (device_uri = cupsGetOption("device-uri", dest->num_options, dest->options)) != NULL && !strncmp(device_uri, "dnssd://", 8))
+ {
+ /*
+ * Add existing queue using service name, etc. so we don't list it again...
+ */
+
+ char scheme[32], /* URI scheme */
+ userpass[32], /* Username:password */
+ serviceName[256], /* Service name (host field) */
+ resource[256], /* Resource (options) */
+ *regtype, /* Registration type */
+ *replyDomain; /* Registration domain */
+ int port; /* Port number (not used) */
+
+ if (httpSeparateURI(HTTP_URI_CODING_ALL, device_uri, scheme, sizeof(scheme), userpass, sizeof(userpass), serviceName, sizeof(serviceName), &port, resource, sizeof(resource)) >= HTTP_URI_STATUS_OK)
+ {
+ if ((regtype = strstr(serviceName, "._ipp")) != NULL)
+ {
+ *regtype++ = '\0';
+
+ if ((replyDomain = strstr(regtype, "._tcp.")) != NULL)
+ {
+ replyDomain[5] = '\0';
+ replyDomain += 6;
+
+ if ((device = cups_dnssd_get_device(&data, serviceName, regtype, replyDomain)) != NULL)
+ device->state = _CUPS_DNSSD_ACTIVE;
+ }
+ }
+ }
+ }
#endif /* HAVE_DNSSD || HAVE_AVAHI */
+ }
- return (1);
+ cupsFreeDests(num_dests, dests);
+
+ if (i > 0 || msec == 0)
+ goto enum_finished;
}
+ /*
+ * Return early if the caller doesn't want to do discovery...
+ */
+
+ if ((mask & CUPS_PRINTER_DISCOVERED) && !(type & CUPS_PRINTER_DISCOVERED))
+ goto enum_finished;
+
#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
/*
* Get Bonjour-shared printers...
# endif /* HAVE_AVAHI */
}
- cupsArrayDelete(data.devices);
-
# ifdef HAVE_DNSSD
DNSServiceRefDeallocate(ipp_ref);
DNSServiceRefDeallocate(local_ipp_ref);
# endif /* HAVE_DNSSD */
#endif /* HAVE_DNSSD || HAVE_DNSSD */
+ /*
+ * Return...
+ */
+
+ enum_finished:
+
+#if defined(HAVE_DNSSD) || defined(HAVE_AVAHI)
+ cupsArrayDelete(data.devices);
+#endif /* HAVE_DNSSD || HAVE_AVAHI */
+
return (1);
}
/*
* 'cupsEnumDestsBlock()' - Enumerate available destinations with a block.
*
- * Destinations are enumerated from one or more sources. The block receives the
- * destination name, instance, number of options, and options which can be used
- * as input to the @link cupsAddDest@ function. The block must return 1 to
+ * Destinations are enumerated from one or more sources. The block receives the
+ * @code user_data@ pointer and the destination pointer which can be used as
+ * input to the @link cupsCopyDest@ function. The block must return 1 to
* continue enumeration or 0 to stop.
*
+ * The @code type@ and @code mask@ arguments allow the caller to filter the
+ * destinations that are enumerated. Passing 0 for both will enumerate all
+ * printers. The constant @code CUPS_PRINTER_DISCOVERED@ is used to filter on
+ * destinations that are available but have not yet been added locally.
+ *
* Enumeration happens on the current thread and does not return until all
* destinations have been enumerated or the block returns 0.
*
- * @since CUPS 1.6/macOS 10.8@
+ * Note: The block will likely receive multiple updates for the same
+ * destinations - it is up to the caller to suppress any duplicate destinations.
+ *
+ * @since CUPS 1.6/macOS 10.8@ @exclude all@
*/
int /* O - 1 on success, 0 on failure */
/*
* 'cupsGetDest()' - Get the named destination from the list.
*
- * Use the @link cupsGetDests@ or @link cupsGetDests2@ functions to get a
+ * Use the @link cupsEnumDests@ or @link cupsGetDests2@ functions to get a
* list of supported destinations for the current user.
*/
* 'cupsGetDests()' - Get the list of destinations from the default server.
*
* Starting with CUPS 1.2, the returned list of destinations include the
- * printer-info, printer-is-accepting-jobs, printer-is-shared,
- * printer-make-and-model, printer-state, printer-state-change-time,
- * printer-state-reasons, and printer-type attributes as options. CUPS 1.4
- * adds the marker-change-time, marker-colors, marker-high-levels,
- * marker-levels, marker-low-levels, marker-message, marker-names,
- * marker-types, and printer-commands attributes as well.
+ * "printer-info", "printer-is-accepting-jobs", "printer-is-shared",
+ * "printer-make-and-model", "printer-state", "printer-state-change-time",
+ * "printer-state-reasons", "printer-type", and "printer-uri-supported"
+ * attributes as options.
+ *
+ * CUPS 1.4 adds the "marker-change-time", "marker-colors",
+ * "marker-high-levels", "marker-levels", "marker-low-levels", "marker-message",
+ * "marker-names", "marker-types", and "printer-commands" attributes as options.
+ *
+ * CUPS 2.2 adds accessible IPP printers to the list of destinations that can
+ * be used. The "printer-uri-supported" option will be present for those IPP
+ * printers that have been recently used.
*
* Use the @link cupsFreeDests@ function to free the destination list and
* the @link cupsGetDest@ function to find a particular destination.
+ *
+ * @exclude all@
*/
int /* O - Number of destinations */
* 'cupsGetDests2()' - Get the list of destinations from the specified server.
*
* Starting with CUPS 1.2, the returned list of destinations include the
- * printer-info, printer-is-accepting-jobs, printer-is-shared,
- * printer-make-and-model, printer-state, printer-state-change-time,
- * printer-state-reasons, and printer-type attributes as options. CUPS 1.4
- * adds the marker-change-time, marker-colors, marker-high-levels,
- * marker-levels, marker-low-levels, marker-message, marker-names,
- * marker-types, and printer-commands attributes as well.
+ * "printer-info", "printer-is-accepting-jobs", "printer-is-shared",
+ * "printer-make-and-model", "printer-state", "printer-state-change-time",
+ * "printer-state-reasons", "printer-type", and "printer-uri-supported"
+ * attributes as options.
+ *
+ * CUPS 1.4 adds the "marker-change-time", "marker-colors",
+ * "marker-high-levels", "marker-levels", "marker-low-levels", "marker-message",
+ * "marker-names", "marker-types", and "printer-commands" attributes as options.
+ *
+ * CUPS 2.2 adds accessible IPP printers to the list of destinations that can
+ * be used. The "printer-uri-supported" option will be present for those IPP
+ * printers that have been recently used.
*
* Use the @link cupsFreeDests@ function to free the destination list and
* the @link cupsGetDest@ function to find a particular destination.
data.num_dests = 0;
data.dests = NULL;
- cupsEnumDests(0, 1000, NULL, 0, CUPS_PRINTER_3D, (cups_dest_cb_t)cups_get_cb, &data);
+ cupsEnumDests(0, 1000, NULL, 0, 0, (cups_dest_cb_t)cups_get_cb, &data);
if (cupsLastError() >= IPP_STATUS_REDIRECTION_OTHER_SITE)
{
* 'cupsGetNamedDest()' - Get options for the named destination.
*
* This function is optimized for retrieving a single destination and should
- * be used instead of @link cupsGetDests@ and @link cupsGetDest@ when you either
- * know the name of the destination or want to print to the default destination.
- * If @code NULL@ is returned, the destination does not exist or there is no
- * default destination.
+ * be used instead of @link cupsGetDests2@ and @link cupsGetDest@ when you
+ * either know the name of the destination or want to print to the default
+ * destination. If @code NULL@ is returned, the destination does not exist or
+ * there is no default destination.
*
* If "http" is @code CUPS_HTTP_DEFAULT@, the connection to the default print
* server will be used.
* Get the printer's attributes...
*/
- if (!_cupsGetDests(http, op, name, &dest, 0, CUPS_PRINTER_3D))
+ if (!_cupsGetDests(http, op, name, &dest, 0, 0))
{
if (name)
{
data.name = name;
data.dest = NULL;
- cupsEnumDests(0, 1000, NULL, 0, CUPS_PRINTER_3D, (cups_dest_cb_t)cups_name_cb, &data);
+ cupsEnumDests(0, 1000, NULL, 0, 0, (cups_dest_cb_t)cups_name_cb, &data);
if (!data.dest)
return (NULL);
*
* This function saves the destinations to /etc/cups/lpoptions when run
* as root and ~/.cups/lpoptions when run as a normal user.
+ *
+ * @exclude all@
*/
void
* Get the server destinations...
*/
- num_temps = _cupsGetDests(http, IPP_OP_CUPS_GET_PRINTERS, NULL, &temps, 0, CUPS_PRINTER_3D);
+ num_temps = _cupsGetDests(http, IPP_OP_CUPS_GET_PRINTERS, NULL, &temps, 0, 0);
if (cupsLastError() >= IPP_STATUS_REDIRECTION_OTHER_SITE)
{
* Note: This function is needed because avahi_simple_poll_iterate is broken
* and always uses a timeout of 0 (!) milliseconds.
* (Avahi Ticket #364)
+ *
+ * @private@
*/
static int /* O - Number of file descriptors matching */
model[256], /* Model */
uriname[1024], /* Name for URI */
uri[1024]; /* Printer URI */
- cups_ptype_t type = CUPS_PRINTER_REMOTE | CUPS_PRINTER_BW;
+ cups_ptype_t type = CUPS_PRINTER_DISCOVERED | CUPS_PRINTER_BW;
/* Printer type */
int saw_printer_type = 0;
/* Did we see a printer-type key? */
*/
saw_printer_type = 1;
- type = (cups_ptype_t)strtol(value, NULL, 0);
+ type = (cups_ptype_t)strtol(value, NULL, 0) | CUPS_PRINTER_DISCOVERED;
}
else if (!saw_printer_type)
{