# 16 Locating services in a network: `Discovery`

### Andreas Sundström

In order to make it easier to find a service (an Oz server application) one might want to have some sort of yellow pages, or a directory. While a directory is easy to implement in Oz, the `Discovery` module allows to locate it in a local area network.

The current implementation may be incomplete on certain platforms. Notably, only on Linux and Solaris it is guaranteed that broadcasts are sent to all the available networks. On other platforms this depends on the operating system.

The `Discovery` service consists of two parts, a server and a client. The server is initialized with a value. The server waits for inquiries from clients and sends the value as an answer. The client sends a broadcast message to all available networks (for example, ethernet and ip over serial link). Then the client waits for answers from servers.

A value the server holds would typically be a ticket to an Oz port that a directory server listens to.

## 16.1 The Module

The module has three features:

`server`

  The server class.

`client`

  The client class.

`defaultServerPort`

  The number of the default ip port that the server listens to.

The server class `Discovery.server` has following methods:

`init`

  > `init(info:``Info` `port:``PortNr``<=` `DefaultServerPort``)`

  `Info` is the answer to be send on request by clients. It must be a virtual string. The server listens to the ip port `PortNr`. If the field `port` is not present, the default port number will be used.

`replace`

  > `replace(info:Info)`

  Replaces the answer to be send to clients.

`close`

  > `close()`

  Closes the operation of the server.

The client class `Discovery.client` has following methods:

`init`

  > `init(port:``ServerPortNr``<=` `DefaultServerPort``)`

  This method broadcasts a message. Answers to that message can be obtained using the methods `getOne` and `getAll`. The port that the server listens can be specified as `ServerPortNr`. If the field `port` is not present, the default port number will be used.

`getOne`

  > `getOne(timeOut:``TimeOut``<= 1000 info:?``Info``)`

  There could be several servers listening to broadcasts from a client, therefore there can be several answers. If an answer is received before `TimeOut` milliseconds the variable `Info` will hold that answer. Otherwise `Info` will be `timeout`. Answers are Oz strings.

  Instead of a time in milliseconds `TimeOut` can be `inf`. This means that the method will suspend until an answer is received (or forever if no answer is received).

  If this method is called again the next answer (if such answer exists) will be returned.

`getAll`

  > `getAll(timeOut:``TimeOut``<= 1000 info:?``Info``)`

  Method `getAll` can be used instead of method `getOne`. After calling this method, `Info` will hold a list of all answers received before `TimeOut` milliseconds has gone by.

  This method is implemented using `getOne`. So any answers fetched by calling `getOne` will not reappear in the list `Info`, and vice versa.

  `TimeOut` can be `inf` here too. In this case a stream will be returned instead of a list.

`close`

  > `close()`

  Closes the operation of the client class.