# Understanding the managed resource

Before designing a Natural Access service, you must understand exactly what the managed resource is and how it operates. For example, if the managed resource is a telephony board, then you must first understand the low-level details of inter-operating with the telephony board such as how to:

- Initialize the board.

- Send commands to the board.

- Process messages from the board.

You can then define a simple, intuitive Natural Access API to the managed resource. Suggested action items include:

1. API analysis
   Create a list of managed resource interface calls and then determine if any of those calls can be combined into a smaller set of simpler, more abstract functions.

2. Event analysis

- Itemize the list of all incoming messages (raw events) from the managed resource and determine which of these messages should be processed and forwarded to a client. By definition, the remaining messages (if any) are processed and consumed.

- Determine whether the managed resource is multiplexed (that is, whether you can use one wait object for events from the managed resource or the managed resource requires multiple wait objects). If the messages sent to and from the managed resource contain addressing information describing the identity of the caller, the managed resource is multiplexed (that is, requires only one wait object).

3. Data abstraction analysis
   When appropriate, create data structures to model the managed resource in software as follows:

- A data structure that contains information about the managed resource itself.

- A data structure that contains information pertaining to a client of the managed resource.

- Zero or more data structures containing information pertaining to entities that can be manipulated by a client on the managed resource.

There are at least two types of information that are useful during this phase:

- A documented interface to the managed resource. This documentation can be used as a baseline for defining the corresponding simpler, more abstract Natural Access service API. Without documentation, the interface must be discerned from the implementation of the managed resource.

- Documented internal behavior of the managed resource, such as state diagrams or interaction diagrams.

In Natural Access parlance, a managed resource is represented and referred to as a service object. The data structure that contains information pertaining to a client of the service object is referred to as an instance of a service object.

tik service

The managed resource for the tik service is a software timer known as the tik server. The tik server operates as a software timer. It waits for a certain interval to expire then generates and sends a text message over a well-defined IPC channel to a client until a maximum number of messages is generated. The client specifies the timer interval and maximum number of messages; the text message is configured at server initialization time and is not dynamically configurable. The tik server can support, at most, 10 separate channels per client.

Commands can be sent from a client to the tik server that:

- Request a connection with the tik server.

- Allocate a logical channel.

- Start timer on a logical channel based upon number of ticks to generate and duration between ticks.

- Stop timer on a logical channel before all tick strings are received.

- Request a channel tear down.

When the tik server generates all tick messages, the logical channel is left active so that another start tick request can be serviced.

If a client sends a stop request string to the server, the server aborts the generation of remaining ticks. The logical channel remains active for further start tick requests.

Using the description of the tik server, the following information summarizes the results of the suggested action items:

Analysis of interaction with tik server

Based on the list of messages to be generated by a tik server client, the abstracted set of API calls are:

- A function to start a ticker

- A function to stop a ticker

- A function to request information concerning the status of the logical connection

Event identification and processing

The following is a list of incoming messages received from the tik server:

- An open channel response message indicating whether a communications channel was established with the server.

- A stop ticking message indicating that a request to abnormally terminate generation of tick strings has been honored.

- A tick message containing the periodic tick string.

The tik server is multiplexed in that all messages to and from the server contain a field denoting the id of the client.

Abstract data structures

The managed resource data structure should contain:

- Communications endpoint for the tik server

- Status fields for communications with the tik server including when a read is pending and how many reads have been performed.

- Storage for the latest message received from the tik server

- Array of logical channels that are active

- The client-specific data structure for the managed resource should contain the:

- Associated Natural Access context handle (the client id)

- Actual logical channel id being used

- State of the logical channel

- Tracemask for per-context tracing

The software timer is the only entity to be manipulated by a tik server client. Similarly, a client can only manipulate one of them at a time. Therefore, it is not necessary to define explicit entity data structures.