nut-scanner: implement iteration across nutscan_ip_range_list_t colle…

…ction [networkupstools#2511]

Signed-off-by: Jim Klimov <[email protected]>

NEWS.adoc

@@ -147,7 +147,7 @@ installed.
      An `/ADDRLEN` suffix can be added to the option, to filter out discovered
      subnets with too many bits available for the host address part (avoiding
      millions of scans in the extreme cases).
-     [issue #2244, PR #2509, PR #2513, PR #2517]
+     [issue #2244, issue #2511, PR #2509, PR #2513, PR #2517]
    * bumped version of `libnutscan` to 2.5.2, it now includes a few more
      methods and symbols from `libcommon`. [issue #2244, PR #2509]
 

docs/man/Makefile.am

@@ -201,6 +201,8 @@ SRC_DEV_PAGES = \
 	nutscan_init_ip_ranges.txt \
 	nutscan_free_ip_ranges.txt \
 	nutscan_add_ip_range.txt \
+	nutscan_ip_ranges_iter_init.txt \
+	nutscan_ip_ranges_iter_inc.txt \
 	nutscan_cidr_to_ip.txt \
 	nutscan_new_device.txt \
 	nutscan_free_device.txt \
@@ -322,6 +324,8 @@ MAN3_DEV_PAGES = \
 	nutscan_init_ip_ranges.3 \
 	nutscan_free_ip_ranges.3 \
 	nutscan_add_ip_range.3 \
+	nutscan_ip_ranges_iter_init.3 \
+	nutscan_ip_ranges_iter_inc.3 \
 	nutscan_cidr_to_ip.3 \
 	nutscan_new_device.3 \
 	nutscan_free_device.3 \
@@ -338,6 +342,18 @@ upscli_readline_timeout.3: upscli_readline.3
 upscli_sendline_timeout.3: upscli_sendline.3
 	touch $@
 
+nutscan_scan_ip_range_snmp.3: nutscan_scan_snmp.3
+	touch $@
+
+nutscan_scan_ip_range_xml_http.3: nutscan_scan_xml_http_range.3
+	touch $@
+
+nutscan_scan_ip_range_nut.3: nutscan_scan_nut.3
+	touch $@
+
+nutscan_scan_ip_range_ipmi.3: nutscan_scan_ipmi.3
+	touch $@
+
 nutscan_add_commented_option_to_device.3: nutscan_add_option_to_device.3
 	touch $@
 
@@ -400,6 +416,8 @@ HTML_DEV_MANS = \
 	nutscan_init_ip_ranges.html \
 	nutscan_free_ip_ranges.html \
 	nutscan_add_ip_range.html \
+	nutscan_ip_ranges_iter_init.html \
+	nutscan_ip_ranges_iter_inc.html \
 	nutscan_cidr_to_ip.html \
 	nutscan_new_device.html \
 	nutscan_free_device.html \
@@ -416,6 +434,10 @@ HTML_DEV_MANS = \
 HTML_DEV_MANS_FICTION = \
 	upscli_readline_timeout.html \
 	upscli_sendline_timeout.html \
+	nutscan_scan_ip_range_snmp.html \
+	nutscan_scan_ip_range_xml_http.html \
+	nutscan_scan_ip_range_nut.html \
+	nutscan_scan_ip_range_ipmi.html \
 	nutscan_add_commented_option_to_device.html
 
 upscli_readline_timeout.html: upscli_readline.html
@@ -424,6 +446,18 @@ upscli_readline_timeout.html: upscli_readline.html
 upscli_sendline_timeout.html: upscli_sendline.html
 	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
 
+nutscan_scan_ip_range_snmp.html: nutscan_scan_snmp.html
+	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
+
+nutscan_scan_ip_range_xml_http.html: nutscan_scan_xml_http_range.html
+	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
+
+nutscan_scan_ip_range_nut.html: nutscan_scan_nut.html
+	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
+
+nutscan_scan_ip_range_ipmi.html: nutscan_scan_ipmi.html
+	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
+
 nutscan_add_commented_option_to_device.html: nutscan_add_option_to_device.html
 	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
 

docs/man/nutscan_add_ip_range.txt

@@ -71,4 +71,6 @@ SEE ALSO
 --------
 
 linkman:nutscan_init_ip_ranges[3], linkman:nutscan_free_ip_ranges[3],
-linkman:nutscan_cidr_to_ip[3]
+linkman:nutscan_cidr_to_ip[3],
+linkman:nutscan_ip_ranges_iter_init[3],
+linkman:nutscan_ip_ranges_iter_inc[3]

docs/man/nutscan_free_ip_ranges.txt

@@ -37,4 +37,6 @@ SEE ALSO
 --------
 
 linkman:nutscan_init_ip_ranges[3], linkman:nutscan_add_ip_range[3],
-linkman:nutscan_cidr_to_ip[3]
+linkman:nutscan_cidr_to_ip[3],
+linkman:nutscan_ip_ranges_iter_init[3],
+linkman:nutscan_ip_ranges_iter_inc[3]

docs/man/nutscan_init_ip_ranges.txt

@@ -38,4 +38,6 @@ SEE ALSO
 --------
 
 linkman:nutscan_free_ip_ranges[3], linkman:nutscan_add_ip_range[3],
-linkman:nutscan_cidr_to_ip[3]
+linkman:nutscan_cidr_to_ip[3],
+linkman:nutscan_ip_ranges_iter_init[3],
+linkman:nutscan_ip_ranges_iter_inc[3]

docs/man/nutscan_ip_ranges_iter_inc.txt

@@ -0,0 +1,44 @@
+NUTSCAN_IP_RANGES_ITER_INC(3)
+=============================
+
+NAME
+----
+
+nutscan_ip_ranges_iter_inc - Proceed with iteration of an IP address range
+using a `nutscan_ip_range_list_iter_t` structure.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ char * nutscan_ip_ranges_iter_inc(nutscan_ip_range_list_iter_t *irliter);
+
+DESCRIPTION
+-----------
+
+The *nutscan_ip_ranges_iter_inc()* function can prepare an iterator from
+the specified `nutscan_ip_range_list_t` structure.
+
+This function skips work if:
+
+* the structure pointer is `NULL` (`NULL` is returned);
+* the structure pointer's `ip_range` list is `NULL` (`NULL` is returned),
+* the structure pointer's `ip_range_iter` pointer is `NULL` (`NULL` is
+  returned).
+
+Returns the next IP address from the currently iterated registered IP
+address range, or switches iteration to the next range if no addresses
+remained in the current one.
+
+NOTES
+-----
+
+Technically, the function is currently defined in 'nutscan-ip.h' file.
+
+SEE ALSO
+--------
+
+linkman:nutscan_init_ip_ranges[3], linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_cidr_to_ip[3],
+linkman:nutscan_ip_ranges_iter_init[3]

docs/man/nutscan_ip_ranges_iter_init.txt

@@ -0,0 +1,48 @@
+NUTSCAN_IP_RANGES_ITER_INIT(3)
+==============================
+
+NAME
+----
+
+nutscan_ip_ranges_iter_init - Begin iteration of an IP address range using
+a `nutscan_ip_range_list_iter_t` structure.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ char * nutscan_ip_ranges_iter_init(
+    nutscan_ip_range_list_iter_t *irliter,
+    const nutscan_ip_range_list_t *irl);
+
+DESCRIPTION
+-----------
+
+The *nutscan_ip_ranges_iter_init()* function can prepare an iterator from
+the specified `nutscan_ip_range_list_t` structure, saving it into the
+caller-provided `nutscan_ip_range_list_iter_t` helper object.
+
+Different iterators may be created to walk the same `nutscan_ip_range_list_t`
+list from different scans independently, but the list and its contents should
+not be freed while anyone references it.
+
+This function skips work if:
+
+* the structure pointer is `NULL` (`NULL` is returned);
+* the structure pointer's `ip_range` list is `NULL` (`NULL` is returned).
+
+Returns the first IP address from the first registered IP address range.
+Subsequent addresses can be returned by `nutscan_ip_ranges_iter_inc()`.
+
+NOTES
+-----
+
+Technically, the function is currently defined in 'nutscan-ip.h' file.
+
+SEE ALSO
+--------
+
+linkman:nutscan_init_ip_ranges[3], linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_cidr_to_ip[3],
+linkman:nutscan_ip_ranges_iter_inc[3]

docs/man/nutscan_scan_ipmi.txt

@@ -12,22 +12,29 @@ SYNOPSIS
  #include <nut-scan.h>
 
  nutscan_device_t * nutscan_scan_ipmi(
-       const char * startIP,
-       const char * stopIP,
-       nutscan_ipmi_t * sec);
+        const char * startIP,
+        const char * stopIP,
+        nutscan_ipmi_t * sec);
+
+ nutscan_device_t * nutscan_scan_ip_range_ipmi(
+        nutscan_ip_range_list_t * irl,
+        nutscan_ipmi_t * sec);
 
 DESCRIPTION
 -----------
 
-The *nutscan_scan_ipmi()* function tries to detect IPMI manageable devices.
+The *nutscan_scan_ipmi()* and *nutscan_scan_ip_range_ipmi()* functions
+try to detect IPMI manageable devices.
 
-If 'start_ip' is NULL, the function searches for a local PSU.
+If 'start_ip' for the former or 'irl' for the latter are NULL, the
+respective function searches for a local PSU.
 
 Otherwise, it searches for remote hosts that would serve IPMI protocols,
 and would try to authenticate using the data in 'sec' structure.
-It issues a NUT request on every IP ranging from 'startIP' to 'stopIP',
-where 'stopIP' is optional. Those IP arguments may be either IPv4 or IPv6
-addresses or host names.
+The former issues an IPMI request on every IP ranging from 'startIP' to
+'stopIP', where 'stopIP' is optional; the latter can walk several IP
+address ranges represented by a `nutscan_ip_range_list_t` structure.
+Those IP arguments may be either IPv4 or IPv6 addresses or host names.
 
 You MUST call linkman:nutscan_init[3] before using this function.
 
@@ -57,5 +64,7 @@ linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
-linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],
+linkman:nutscan_init_ip_ranges[3],
+linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_add_ip_range[3],
 linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_scan_nut.txt

@@ -18,13 +18,21 @@ SYNOPSIS
         const char * port,
         useconds_t usec_timeout);
 
+ nutscan_device_t * nutscan_scan_ip_range_nut(
+        nutscan_ip_range_list_t * irl,
+        const char * port,
+        useconds_t usec_timeout);
+
 DESCRIPTION
 -----------
 
-The *nutscan_scan_nut()* function try to detect available NUT services
-and their associated devices. It issues a NUT request on every IP ranging
-from 'startIP' to 'stopIP'. 'startIP' is mandatory, 'stopIP' is optional.
-Those IP arguments may be either IPv4 or IPv6 addresses or host names.
+The *nutscan_scan_nut()* and *nutscan_scan_ip_range_nut()* functions
+try to detect available NUT services and their associated devices.
+The former issues a NUT request on every IP ranging from 'startIP'
+to 'stopIP' (where 'startIP' is mandatory, 'stopIP' is optional);
+the latter can walk several IP address ranges represented by a
+`nutscan_ip_range_list_t` structure. Those IP arguments may be
+either IPv4 or IPv6 addresses or host names.
 
 You MUST call linkman:nutscan_init[3] before using this function.
 
@@ -54,4 +62,7 @@ linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],
+linkman:nutscan_init_ip_ranges[3],
+linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_add_ip_range[3],
 linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_scan_snmp.txt

@@ -18,12 +18,19 @@ SYNOPSIS
         useconds_t timeout,
         nutscan_snmp_t * sec);
 
+ nutscan_device_t * nutscan_scan_ip_range_snmp(
+        nutscan_ip_range_list_t * irl,
+        useconds_t usec_timeout,
+        nutscan_snmp_t * sec);
+
 DESCRIPTION
 -----------
 
-The *nutscan_scan_snmp()* function try to detect NUT compatible SNMP
-devices. It tries SNMP queries on every IP ranging from 'start_ip' to
-'stop_ip'. Those IP arguments may be either IPv4 or IPv6 addresses or
+The *nutscan_scan_snmp()* and *nutscan_scan_ip_range_snmp()* functions
+try to detect NUT compatible SNMP devices. The former tries SNMP queries
+on every IP ranging from 'start_ip' to 'stop_ip'; the latter can walk
+several IP address ranges represented by a `nutscan_ip_range_list_t`
+structure. Those IP arguments may be either IPv4 or IPv6 addresses or
 host names.
 
 You MUST call linkman:nutscan_init[3] before using this function.
@@ -90,4 +97,7 @@ linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],
+linkman:nutscan_init_ip_ranges[3],
+linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_add_ip_range[3],
 linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_scan_xml_http_range.txt

@@ -18,16 +18,24 @@ SYNOPSIS
         useconds_t usec_timeout,
         nutscan_xml_t * sec)
 
+ nutscan_device_t * nutscan_scan_ip_range_xml_http(
+        nutscan_ip_range_list_t * irl,
+        useconds_t usec_timeout,
+        nutscan_xml_t * sec)
+
 DESCRIPTION
 -----------
 
-The *nutscan_scan_xml_http_range()* function tries to detect NUT compatible
-XML/HTTP devices.
+The *nutscan_scan_xml_http_range()* and *nutscan_scan_ip_range_xml_http()*
+functions try to detect NUT compatible XML/HTTP devices.
 
-If 'start_ip' is NULL, the function does this by issuing a broadcast message
-on currently configured network interfaces.
+If 'start_ip' for the former or 'irl' for the latter are NULL, the
+respective function does this by issuing a broadcast message on all
+currently configured network interfaces.
 
-Otherwise, it queries every IP ranging from 'start_ip' to 'stop_ip'.
+Otherwise, the former queries every IP ranging from 'start_ip' to 'stop_ip',
+where 'stopIP' is optional; the latter can walk several IP address ranges
+represented by a `nutscan_ip_range_list_t` structure.
 Those IP arguments may be either IPv4 or IPv6 addresses or host names.
 
 It waits up to 'usec_timeout' microseconds for a response from potential
@@ -55,4 +63,8 @@ linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
-linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3]
+linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],
+linkman:nutscan_init_ip_ranges[3],
+linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_add_ip_range[3],
+linkman:nutscan_cidr_to_ip[3]

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3182 utf-8
+personal_ws-1.1 en 3185 utf-8
 AAC
 AAS
 ABI
@@ -1698,6 +1698,7 @@ cts
 ctypes
 cua
 cuaa
+curr
 customizations
 cvt
 cwd
@@ -2092,11 +2093,13 @@ ippon
 ipv
 ipxe
 irl
+irliter
 isDefault
 isbmex
 ish
 iso
 isolator
+iter
 ivtscd
 jNUT
 jNut