comand::discover()

This method will not be implemented until after API version 1.0.

The discover method of a comand object provides a way to find COMAND Repositories available on a computer, network or the Internet. Repositories will be discovered using the following means:

Configuration - Hosts defined in the configuration file or comand object options.
Connected Repositories - Repositories already connected with this COMAND object.
Known Repositories - Repositories known to any of the connected repositories.
Scanned Repositories - Repositories detected on the local computer or network. By default, this is accomplished by making web service requests on port 80 (HTTP) and 443 (HTTPS).

Multiple threads are used to more efficiently scan networks and the Internet. Use the callback option to allow the scan process to work in the background and report back with newly discovered hosts at an interval.

Prototype

void discover(array $options = [])

Parameters

options (optional) - Associative array of options to override defaults.
- locations - Specifies which high-level network segmants to search for COMAND repository hosts. One or more of the following constants may be combined with a bitwise OR.
  - DISCOVER_LOCAL - Attempt to connect to a repository on the local computer using the default or specified storage engine and credentials. If no storage engine or credentials are available, attempt to connect to each supported storage engine as a guest (no username or password). Any successfully established connections will remain open until the comand object is destroyed or the server disconnects. The connect method will recognized and reuse an existing connection.
  - DISCOVER_NETWORK - Scan the local network by making a web service discover request on the default web service ports (80 and 443) of every IP address on each adapter's configured network, according to the network and netmask.
  - DISCOVER_INTERNET - Search the Internet for COMAND repository hosts. The methods used to search the internet are yet to be determined, but will likely use a peer-to-peer hybrid model with no single central server (many nodes and hubs).
- timeout - Number of seconds to wait for a response when attempting to connect to a local server or hear back from a web service before it is considered unavailable (at least temporarily).
- max_hosts - Maximum number of hosts to discover before searching is stopped.
- max_hops - Number of hops to search from initial network and known hosts.
- hop_timeout - Number of seconds to wait for each hop to respond. The default is timeout * hops. However, with a large number of hops, it may be desirable to timeout more quickly to free up connections faster.
- callback - An associative array of callback options.
  - interval - Maximum number of seconds to wait before callback is called, even if no new hosts were discovered. A value of 0 will not callback until the callback_hosts are discovered.
  - hosts - Number of hosts to discover before the callback is called.
  - func - An anonymous function or callable to call after callback_interval, callback_hosts or max_hosts is reached. The function should have two parameters:
    - $hosts - An array of associative arrays that represent the host information. See connect method options for an explanation of the keys and their values. In addition to those, a 'repo' key is assigned a reference to a repository object that represents a connection to the repository. It is possible $hosts will be an empty array if no hosts were found and the callback interval or timeout have been reached.
    - $done - Boolean value that will be TRUE if it is the last time the callback will be called for a discover process. The last callaback occurs when the discover process timeout is reached or max_hosts have been returned to the callback.

Return

No value is returned because discover returns immediately, before hosts have been discovered. Use $options['callback']['func'] to specify a callback function to receive hosts as they are discovered.

Example

$comand->discover([
    'locations' => DISCOVER_LOCAL|DISCOVER_NETWORK|DISCOVER_INTERNET,
    'timeout' => 60,
    'max_hosts' => 16,
    'max_hops' => 3,
    'hop_timeout' => 30,
    'callback' => [
        'interval' => 10,
        'hosts' => 3,
        'func' => function discovered_hosts(array $hosts, bool $done) {
            foreach($hosts as $repo) {
                echo($repo->hostname . " (" . $repo->ip . ")\n");
                // to connect: $repo->connect();
            }
        }
    ]
]);