nut/tools/nut-scanner/README

NUT device discovery
====================

Introduction
------------

linkman:nut-scanner[8] is available to discover supported NUT devices
(USB, SNMP, Eaton XML/HTTP and IPMI) and NUT servers (using Avahi or the
classic connection method).

This tool actually use a library, called *libnutscan*, to perform actual
processing.


Client access library
~~~~~~~~~~~~~~~~~~~~~

The nutscan library can be linked into other programs to give access
to NUT discovery. Both static and shared versions are provided.

linkman:nut-scanner[8] is provided as an example of how to use the nutscan
functions.

Here is a simple example that scans for USB devices, and use its own
iteration function to display results:

	#include <stdlib.h>
	#include <unistd.h>
	#include <string.h>

	/* Only enable USB scan */
	#define HAVE_USB_H

	#include "nut-scan.h"

	int main()
	{
		nutscan_options_t * opt;
		nutscan_device_t *device;

		nutscan-init();

		if ((device = nutscan_scan_usb()) == NULL) {
			printf("No device found\n");
			exit(EXIT_FAILURE);
		}

		/* Rewind the list */
		while(device->prev != NULL) {
			device = device->prev;
		}

		/* Print results */
		do {
			printf("USB device found\n\tdriver: \"%s\"\n\tport: \"%s\"\n",
				device->driver, device->port);

			/* process options (serial number, bus, ...) */
			opt = &(device->opt);
			do {
				if( opt->option != NULL ) {
					printf("\t%s",opt->option);
					if( opt->value != NULL ) {
						printf(": \"%s\"", opt->value);
					}
					printf("\n");
				}
				opt = opt->next;
			} while( opt != NULL );

			device = device->next;
		}
		while( device != NULL );

		exit(EXIT_SUCCESS);
	}


This library file and the associated header files are not installed by
default.  You must `./configure --with-dev` to enable building and
installing these files. The libraries can then be built and installed
with `make` and `make install` as usual. This must be done before
building other (non-NUT) programs which depend on them.

For more information, refer to the linkman:nutscan[3],
manual page and the various
link:man/index.html#devscan[nutscan_*(3)] functions documentation
referenced in the same file.


Configuration helpers
~~~~~~~~~~~~~~~~~~~~~

NUT provides helper scripts to ease the configuration step of your program, by
detecting the right compilation and link flags.

For more information, refer to a
<<lib-info,Appendix B: NUT libraries complementary information>>.


Python
------

Python support for NUT discovery features is not yet available.


Perl
----

Perl support for NUT discovery features is not yet available.


Java
----

Java support for NUT discovery features is not yet available.