Add note that the callback/block will get multiple calls for the same

destination during enumeration (Issue #5017)

diff --git a/cups/cupspm.md b/cups/cupspm.md
index 5bbce4b5ae5d0cd7fbc2bb2a82524fd66159cc46..c7f86d87dcdb5a10377427506e3ee212c4a4ae88 100644 (file)
--- a/cups/cupspm.md
+++ b/cups/cupspm.md
@@ -197,6 +197,10 @@ can have any of the following constant (bit) values set:
 
 The callback function returns 0 to stop enumeration or 1 to continue.
 
+> Note that the callback function will likely be called multiple times for the
+> same destination, so it is up to the caller to suppress any duplicate
+> destinations.
+
 The following example shows how to use `cupsEnumDests` to get a filtered array
 of destinations:
 

diff --git a/cups/dest.c b/cups/dest.c
index 9c256aa03276666c06fa13689c0fb17a92435326..674d8d2dad75e5d82634598a59932c646873f11b 100644 (file)
--- a/cups/dest.c
+++ b/cups/dest.c
@@ -941,6 +941,9 @@ _cupsCreateDest(const char *name,   /* I - Printer name */
  * 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@
  */
 
@@ -1360,6 +1363,9 @@ cupsEnumDests(
  * Enumeration happens on the current thread and does not return until all
  * destinations have been enumerated or the block returns 0.
  *
+ * 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@
  */