RBNB WebTurbine^TM

Software Developer Manual

V2.1

July 8, 2002

Copyright Creare Inc.

1 Introduction
1.1 Purpose
1.2 Object Overview
1.3 Programming Environments
2 ChannelMaps
2.1 Channel Names
2.2 Channel DataTypes
2.3 Channel TimeStamps
2.4 ChannelMap Registration
2.5 ChannelMap Methods
3 Clients
3.1 Base Client
3.2 Source Client
3.3 Sink Client
3.4 PlugIn Client

1 Introduction

1. 1 Purpose

This manual provides an overview of the RBNB Simple Application Programming Interface (SAPI) for the WebTurbine software. The SAPI is designed to provide maximum capability with minimum complexity. This document is not necessarily a complete reference for all available SAPI methods. For a rigorous reference document, see the associated javadoc package com.rbnb.sapi documentation.

The SAPI is implemented as a set of methods on top of the RBNB Java "RMap" API. Certain concessions are made to optimize portability, such as avoiding the use of overloaded methods. As of this point, the full RMap API is not supported for third party access, but the SAPI is a highly functional, self contained interface to the RBNB.

1.2 Object Overview

There are two main types of objects in the Simple API:

ChannelMap

Client

The ChannelMap object organizes data. ChannelMaps are used by RBNB clients to send, request, and retrieve data from an RBNB server.

A Client object can be one of the following sub-classes:

Source

Sink

PlugIn

An RBNB software developer writes RBNB "clients". Clients communicate with an RBNB server to send and retrieve data. A Source client sends data to the RBNB Server. A Sink fetches data from an RBNB Server. A PlugIn receives requests (from the server on behalf of a Sink) and responds with data (thus acting like both a Sink and Source).

Channel Map

All RBNB data is organized in "channel maps". A channel map consists of a collection of named channels, each with data and timestamp. RBNB clients manipulate channel maps as a means to make requests (sinks) and submit data (sources).

A source client builds a channel map consisting of one or more named channels. For each channel it provides data of a specified type and quantity. It also specifies a timestamp for the channel map as a whole, or for the various pieces (channels and data) separately. After being so built, the channel map is sent from the source client to the RBNB server. This process can be repeated, adding new channels or new data to existing channels.

A sink client builds a channel map in order to request data. Here, the channel map consists of named channels and timestamps, which is sent to the RBNB server as a request. The response to this request is another channel map, this time with the data filled in for the various channels.

Source Client

Source clients are "active", that is they initiate data transmittal to the server. Each time a source sends some data to the server, it is called a "frame". A source can send a sequence of frames to the server. Each frame can consist of one or more named "channels". Each channel can consist of one or more data points per frame.

Key to the idea of RBNB is that all data is time-stamped. Timestamps can be per frame, per channel, and/or per data point. Timestamps can be explicit (provided by the source), or implicit (automatically provided by the client API or RBNB server).

Sink Client

Sink clients are "active", that is they initiate data retrieval from the server. Just as for a source, each time a sink gets frames of data from a server. Each frame consists of one or more named channels, with each channel consisting of one or more data points.

A sink requests data by both channel name(s) and timestamp. The data returned to a sink can consist of multiple or partial source frames, depending upon the requested time slice. There are three modes by which a sink can get data from a server:

Request

Subscribe

Monitor

Requests are for a particular time interval, for which there is a single response for each such request. It is also possible to make a single request that is automatically repeated over a specified number of time intervals.

Subscribe and Monitor modes are open-ended in that new data is automatically sent (from the server to the sink client) as it becomes available. Subscribe mode fetches all data, even if this means falling behind real-time. Monitor mode skips data in order to stay current.

PlugIn Client

PlugIn clients are "passive", that is they wait for data requests from the server, and send data to the server in response to those requests. PlugIns act like a kind of combined sink/source. The server passes to the PlugIn any requests for PlugIn channels. Upon receipt of a request, a PlugIn acts as a source and sends its response to the server.

A PlugIn can optionally register the specific channels that it can provide. Registered channels do not have any data in them, they are a means of "advertising" available channels. With registered channels, only requests for those specific channels will be forwarded by the server to that PlugIn. Otherwise, any request (e.g. "Plugin/anychan") is forwarded to the PlugIn.

Thus, a PlugIn can provide "services" that can involve fetching and processing other RBNB data on the demand of third party applications. PlugIns can process data from other PlugIns, thus cascading sequences of processing steps.

1.3 Programming Environments

The RBNB developer can use one of several programming environments. Whereas this document most directly applies to the Java SAPI, the C/C++, Active X, Java Bean, and other APIs are directly layered on the Java SAPI. Thus, except for minor syntax differences, this documentation is generally applicable for these other APIs as well.

Java

The RBNB server and its API are themselves developed using 100% pure Java. Thus, the core API and its documentation is Java based.

Java Beans

There are extensions to the core Java API to support Java Beans.

Active X

The Java Bean API is further extended via an Active X Bridge to support an Active X interface.

C/C++

There is a C/C++ compatibility layer built on top of the underlying Java API using the "Java Native Interface" (JNI). Most methods follow one-for-one with the underlying Java code.

MATLAB

With Version 6 and later of Matlab, direct calls to Java are supported from the command line mode of Matlab. Thus, Matlab uses the native Java RBNB API directly. Several simple utility M-files are provided as examples.

In order to access the RBNB API from Matlab, you must edit the Matlab classpath.txt file to include the rbnb.jar file. Also, the default Java used by Matlab may not be recent enough to support RBNB. If this is the case, set the MATLAB_JAVA environment variable to a suitable JVM (e.g. C:\JavaSoft\jdk1.3.1\jre).

2 ChannelMap

Clients manipulate data via a "ChannelMap" object. A ChannelMap is comprised of one or more RBNB channels, each consisting of a name, timestamp, and (optional) data.

Channels are individually identified and "staged" using the ChannelMap.Add method prior to being transferred (Fetch or Flush). Behind the scenes, the SAPI incrementally builds up and maintains the underlying "RMap" data structures.

2.1 Channel Names

Multi-tiered hierarchical channel structures can be created, requested, and referenced through a simple directory-like naming convention. A fully specified channel name consists of three main parts:

Server/Source/Channel

Where:

Server:    serverName assigned at Server startup (command line argument)
Source:    clientName given by Source via OpenRBNBConnection method
Channel:   channelName given by Source via ChannelMap.Add method

Data Sources define channels (ChannelMap.Add) with the Server and Source parts implied. The channel name part may itself be multi-tiered, such as:

Chan0
Test43/C0
Test43/C1
A/B/C

Data Sinks request channels (ChannelMap.Add) using either relative or absolute (full-path) names. For example:

/Server/MySource/Test43/C2 # absolute path
MySource/Test43/C2 # relative path

Absolute paths start with a slash, and include the top level (parent) server all the way down to the channel name(s). Relative paths do not start with a slash, and begin with a Source name on the local server.

For Sinks, and when requesting a list of available Server channels, wildcards can also be used, as in:

MySource/Test/...
*/c0
/Server/*/_Msg/...

The following Table summarizes the wildcard syntax available to the ChannelMap.Add (Sink-only) and Client.GetList methods.

**SAPI Channel Naming Wildcard Notation**
Match String	Description
`"*"`	All objects (servers/sources/channels) at this level (one deep)
`"..."`	All channels this level and down (recursive depth). Must be last part of multi-tiered name.
more to come

Note: As of the current release, wildcards are not completely supported.

2.2 Channel DataTypes

ChannelMap Data (PutData) can be specified as a particular primitive data type, per the following table.

**SAPI DataType Codes**
DataType Code	Description
`TYPE_FLOAT32`	Single precision (32 bit) floating point number
`TYPE_FLOAT64`	Double precision (64 bit) floating point number
`TYPE_INT8`	8-bit integer (byte)
`TYPE_INT16`	16-bit integer (short int)
`TYPE_INT32`	32-bit integer (int)
`TYPE_INT64`	64-bit integer (long)
`TYPE_STRING`	Variable length String (character array) object
`TYPE_UNKNOWN`	Unknown or unspecified (byte array)

When specifying a primitive DataType with a word length greater than 8 bits (1 byte), the word order (MSB,LSB) is automatically set to match that of the local native CPU upon which the Source application runs.

2.3 Channel TimeStamps

A Source sets the timestamp for subsequent data transmittal using either a manual (PutTime) or automatic (PutTimeAuto) method.

Each manual timestamp applies to the data specified by one or more subsequent calls to PutData, until a time-setting method is called again. Thus, you can choose to timestamp data point by point, channel by channel, or frame by frame depending on how you interleave your calls to PutTime and PutData.

Automatic time stamps are updated once upon each data Flush. Thus, automatic timestamps are always frame by frame.

RBNB timestamps must monotonically increase. Thus, if you are manually providing timestamps, be sure to never decrease the start time call-to-call.

2.4 ChannelMap Registration

When a Source puts ChannelMaps to a server, the channels are automatically registered. See Sink.RequestRegistration for how to get the ChannelMap from which a list of channel strings may be obtained.

A Source or PlugIn can also specifically register its channels, and in so doing add "metadata" (descriptive information) about the channels. That is, the datablock in the registration ChannelMap is descriptive meta-data about the corresponding Source channel. Since the registration information is not part of the ring-buffer, this meta-data is static (i.e. does not change with time, nor does it "drop off" the ring buffer).

2.5 ChannelMap Methods

2.5.1 Construction

The following ChannelMap methods build, edit and access the list of channels.

`int Add(String channelName)`

Each call to ChannelMap.Add builds up the list of channels to be either sent or fetched by the Source or Sink, respectively. ChannelMap.Add returns an index that increments with the number of channels added. For Sources, this index can be used as the reference index for use in the PutData method. For Sinks, it is possible to get more or less channels than you specify (e.g. using wildcards), so you must inquire (with GetName or GetIndex) which channels have been Fetched.

`void Clear()`

This method clears out the channel map built by the ChannelMap.Add method, and frees associated memory. Use it when you want to build a new channel map from a "clean slate".

2.5.2 Putting Data and Timestamps

The following methods put data in a ChannelMap. These are generally used by Data Sources (and PlugIns).

Note that putting data into a ChannelMap does not send the data to an RBNB server, it builds a local ChannelMap. After building the ChannelMap, it is sent from the client to the RBNB server via the Source.Flush method.

`void PutData(int chanIndex, byte[] rawData, int typeID)`

The generic PutData method sets the data to be sent as a byte-array plus an associated typeID. The typeID is one of the DataTypeCodes. Use the channel index from the associated ChannelMap.Add method, or use the GetIndex method.

Note: Mixing different DataTypes in a single channel is not supported, and may cause difficulties for Sink applications that try to extract mixed-type data.

`void PutDataAsXXX(int chanIndex, XXX[] data)`

The family of PutDataAsXXX methods specifies the primitive type of the supplied data array, where XXX corresponds to one of the DataType Codes. For example, PutDataAsFloat32 lets you directly send a floating point data array with no need to first convert it to a byte array. (Overloaded methods are not used to enhance portability of the SAPI).

Note: PutDataAsString puts a single String object, which is considered to be an indivisible data word.

`void PutTime(int chanIndex, double start, double duration)`

`void PutTimes(double[] times)`

`void PutTimeAuto(String timeMode)`

void PutTimeRef(ChannelMap sourceMap, int channelIndex)

These methods establish the time-stamping method for the ChannelMap. All PutData calls following a PutTime call will be timestamped accordingly. For example, you can call PutTime once for the whole ChannelMap, in which case all data for all channels share a common timestamp. Or you can PutTime separately before every PutData call, giving unique timestamps to every data point for every channel.

2.5.3 Getting Data and Timestamps

The following methods access the data in a ChannelMap. These are generally used by Data Sinks (and PlugIns).

Note that getting data from a ChannelMap does not fetch if from the RBNB server, it extracts it from a local ChannelMap. Prior to getting data, the ChannelMap is sent from the RBNB server to the client via the Sink.Fetch method.

`byte[] GetData(int chanIndex)`

This generic extract data method gets data as a byte-array from the ChannelMap.

`XXX[] GetDataAsXXX(int chanIndex)`

The family of ChannelAsXXX methods specifies the primitive data type of the returned data array, where XXX corresponds to one of the DataType Codes. For example, GetDataAsFloat32 lets you retrieve a floating point data array with no need to convert it from a byte array. If the fetched data does not match the type, an exception will be thrown. You can check the type using the ChannelType method.

Note: GetDataAsString gets an array of String objects, where each String is considered to be an indivisible, individually time-stamped, variable-length data word.

`double[] GetTimes(chanIndex)`

This method returns an array of double precision RBNB time values for the specified channel index. There will be one time point per data point.If necessary, the point times will be linearly interpolated from the underlying start time and duration of the corresponding data array. See PutTime.

2.5.4 DataType Info

These methods provide information about the datatype of a channel.

`int GetType(int chanIndex)`

This method returns a DataType Code for the primitive data type of the fetched data for a given channel. It can be used to determine which of the GetDataAsXXX methods to call.

`int TypeID(String type)`

`String TypeName(int typeID)`

These methods convert the datatype string to numerical constant, and vice versa.

2.5.5 Channel Lists

There are several methods to let you inspect and get the names of the channels in a ChannelMap object. The methods are:

`String GetName(int index)`

This utility method provides a means to get the channel name given the channel index. For Sinks, you can use this method to discover which channels were successfully Fetched.

`int GetIndex(String channelName)`

This utility method provides a means to get the channel index given the channelName. For Sources, the return value of ChannelMap.Add is a reliable channel index. For Sinks, you may need to use this method to determine the reference index of Fetched channels.

`String[] GetChannelList()`

This convenience function is built upon the GetName method. It returns a list of channel names from the channel map. Here, "channels" are defined as RMap nodes that have data.

`String[] GetNodeList()`

This method is like GetChannelList, but it returns a separate entry for every "node" in the ChannelMap. This includes every parent and child node in the channel map tree, i.e. each item delimited by the slash (/) character. For example, if a ChannelMap contains the channel "/Server/Source/Channel", the return result would be "/Server", "/Server/ Source", and "/Server/Source/Channel".

`int[] Search(String mimeType, String keywords)`

This method returns an array of channel indices that match the specified mimeType and keyword string. It is most useful for searching the Registration ChannelMap for channels of interest.

3 Clients

Clients manipulate ChannelMaps to send and receive data from an RBNB server.

3.1 Base Client

The Client class is the base class of all simple clients (Source, Sink, PlugIn) to RBNB servers. The base Client class encapsulates functionality common to all clients.

3.1.1 Client Connections

Clients have methods to open and close connections between the client application and an RBNB server.

`void OpenRBNBConnection(String serverAddress, String clientName, String userName, String password)`

To open a connection identify the server (serverAddress), and identify the client (clientName). The clientName is used for display in applications such as rbnbAdmin, and provides a handle for other applications to administer and access data from this client.

Clients optionally provide a userName and password as part of the connection process. If these are defaulted to NULL, there will be no user name by which you can be granted access to restricted data.

Note: As of the current release, userName and password authorization is not implemented.

`void CloseRBNBConnection(boolean keepCache, boolean keepArchive)`

Upon shutting down a connection, the client application can specify whether or not to maintain data in the cache and/or archive portions of the ring buffer. Specify keepArchive=false to delete the disk archive associated with this connection.

3.1.2 Get Server Info

It is possible to get a the name of the connected server, and of yourself (the connected client).

`String[] GetServerName()`

`String[] GetClientName()`

These methods return the name of the local RBNB server, and the name of the connected client application, respectively.

Memory allocation note for C/C++ programmers:
The data strings returned by the GetName methods are automatically allocated by the API, but are then "owned" and should be released by the client application. A special C/C++ utility function, rbnbFreeStringList(slist, nitem) is provided for this purpose.

3.1.3 Ring Buffer Properties

`SetRingBuffer (int cacheSize, String archiveMode, int archiveSize)`

Clients can set the size of the RBNB server ring buffer associated with its data. Normally, this only applies to Source clients. Sink and PlugIn clients have no existing use for this method (although future enhancements may enable a Sink to manage multiple requests stored on the server).

The cacheSize and archiveSize parameters specify the sizes of the RAM and disk ring buffers (in frames), respectively. Each call to "Flush" by a Source constitutes one "frame".

The archiveMode parameter has one of the following values:

    "none"   - No archive is to be used (default)
    "load"   - Load the archive that matches this application clientName
    "create" - Create a new archive, delete an existing one if one is present
    "append" - Add to an existing archive, create a new one if necessary

3.2 Source Client

An RBNB data source sends data to and RBNB server. A data Source client has the following tasks, which may be repeated as desired:

Define a ChannelMap

Set TimeStamp(s)

Specify data for channel(s)

Flush data to RBNB server

3.2.1 Define Channel Map

A Source channel map is defined by calls to the ChannelMap.Add method. This associates channel names with channel indices, which in turn are used for efficient, potentially repeated references in the ChannelMap.PutData method.

3.2.2 Time Stamps

ChannelMap timestamps are specified using the ChannelMap.PutTime method(s).

3.2.3 Specify Channel Data

The PutData methods specify the channel data to send at the next call to the Flush method. These methods reference the channels by the index returned by ChannelMap.Add. They provide data either as a generic byte-array or as a particular data type.

PutData may be called multiple times per channel per Flush, building up a many-point-per-channel data frame in a piecemeal manner as may be convenient to the application. The SAPI has sophisticated "Deep CVT" logic which automatically consolidates and organizes data into efficient RMap structures. It will always be somewhat more efficient to handle fewer, larger data buffers, however.

Memory allocation note for C/C++ programmers:
The data buffers provided by a source to the API are "owned" by the client application. I.e. the client application is responsible to allocate and free its own data buffers.

3.2.4 Flush Data

Once things are set up, send the data to the server.

`int Source.Flush(ChannelMap cmap, boolean blockingIO)`

After staging information with the time and data setting methods (i.e. PutTime and PutData), the specified channel map is sent as a consolidated RMap with the Flush method.

Each call to Flush involves round-trip network communication, therefore staging larger data frames (with larger buffers and/or multiple calls to PutData) prior to flushing them may provide a significant performance advantage. Of course, you need to also consider the associated impact on memory use and latency when deciding how often to Flush your data.

If the blockingIO parameter is true, it will block until the data is sent. If there is no data to send, calling Flush(cmap,true) will synchronize your application with the server. It returns the number of channels sent.

Note: Flushing the channel map clears the data. Thus, only new data (via PutData) since the previous call to Flush are sent each time.

3.2.5 Source Example Code

The following code opens a connection to a local RBNB server and sends a message string to it.

**Source Example Code**
`Source mySource = new Source();` `mySource.OpenRBNBConnection("localhost", "mySource");` `ChannelMap cmap = new ChannelMap();` `cmap.PutTimeAuto("timeofday");` `int index = cmap.Add("myChan");` `cmap.PutDataAsString(index, "Hello World!");` `mySource.Flush(cmap, true);` `.`

3.3 Sink Client

An RBNB data sink fetches data from and RBNB server. A sink client has the following tasks, repeated as desired:

Specify request ChannelMap

Select sink mode

Fetch response ChannelMap

Extract data and time from response ChannelMap

3.3.1 Request ChannelMap

A Sink clients formulates a request ChannelMap that defines the names and timestamps of the data to be fetched. Channel names are defined by calls to the ChannelMap.Add method, and the associated channel times are defined by calls to the ChannelMap.PutTime method(s).

3.3.2 Sink Modes

There are three types of sink data fetch modes:

Subscribe - All new data is to be streamed without gaps
Monitor - "Current" up-to-date live information is to be sent best-effort.
Request - A particular time-slice of data is requested

Each sink fetch mode applies to the group of channels specified by the ChannelMap.

`void Subscribe(ChannelMap cmap)`

This is the simplest data fetch mode. It takes a channel map as an argument and returns no value. It initiates a streaming "push" of data (from server to client) for all specified channels starting at the time of this call, and proceeding into the future. A single call to Subscribe can be followed by repeated calls to Fetch, where the next frame of data is received. Note that the frame size is determined by the source application(s).

Subscribe is the most efficient mode in that data frames are streamed from the server without waiting for acknowledgment from the sink client. If the client does not keep up, the data delivered will fall further and further behind until it falls off the beginning (oldest) data in the source ring buffer, at which point the stream aborts.

`void Monitor(ChannelMap cmap, int gapControl)`

This provides a variation on the subscribe mode. It initiates a stream of "current" data that will skip-forward as necessary to stay up to date. Full source frames are returned each Fetch. The gapControl argument specifies how many frames behind it can get before it will jump ahead (and miss data) in order to stay current.

When Monitor mode keeps up, it is much like Subscribe, except that there is more round-trip traffic between the client and server for Monitor mode (to establish the gapControl criterion). Unlike Subscribe mode, the stream will not abort if the client doesn't keep up; but data can be dropped with resulting gaps.

Note: As of the current release, the gapcontrol logic is not fully implemented.

`void Request(ChannelMap cmap, double start, double duration, String timeRef)`

The basic Request mode asks for a time-slice of data beginning at start and running for a duration amount. The timeRef argument specifies the time-reference for start. The following table summarizes the various timeRef options.

timeRef	Description
"absolute"	Request a `duration` amount of data at a `start` time specified in absolute-seconds from midnight, Jan 1st, 1970 UTC.
"oldest"	Request a `duration` amount of data where `start` is relative to the oldest available data.
"newest"	Request a `duration` amount of most recent data. Offset the most recent point by `start` amount. E.g. to request "yesterday", use `Request(cmap, OneDay, OneDay, "newest")`
"after"	Request the newest `duration` amount of data, but trim the result to the part that is after the specified `start` time. For example, "send newest data, but only the part newer than what I already have".
"modified"	Request the newest `duration` amount of data, but only send it if at least part of it is newer than the specified `start` time. For example, "send the whole request, but only if at least part of it has changed since the last time".

Note that both start and duration are always positive numbers. For "absolute" and "oldest" time-references, duration extends to right (future) of the start point. For all the other (e.g. "newest") time-references, duration extends to the left (past) of the start point. For example, to get the most recent data, use a start of zero:

sink.Request(cmap, 0, 1, "newest")

There is always one Fetch'd channel map returned for each Request, even if this is a NULL map for the cases where there is no data. A NULL map can occur for the "after" or "modified" cases, or when there is simply no data at the requested time.

`void RequestRegistration(ChannelMap cmap)`

Sends a request to the server for the current registration map for the channels in the specified cmap. The channel map retrieved via the followup Fetch call can be inspected using the ChannelMap.ChannelList method to get a list of channels and other server objects (sources, sinks). The Registration channel map will contain any source-provided metadata.

3.3.3 Fetch Response

After building the ChannelMap and setting the Sink Mode (in that order), get the RBNB data using the Fetch method.

`ChannelMap Fetch(boolean blockingIO)`

This method reads the data from the RBNB server for all channels in the current local Channel List (built by ChannelMap.Add). It returns the number of channels retrieved.

If the blockingIO parameter is true, it will block until the data is retrieved. Otherwise, it will either return a positive integer indicating data was ready and has been read, or a zero (0) indicating no data was yet available.

3.3.4 Extract Data

Fetched data is stored the ChannelMap returned by Fetch. Access to the data and time is via the associated ChannelMap.Get methods.

Memory allocation note for C/C++ programmers:
The data buffers for the fetched data are automatically allocated by the API, but are then "owned" by the client application. I.e. the client application is responsible to free the extracted data and time buffers, using the standard system free() function.

3.3.5 Sink Example Code

The following code snippet will fetch the message sent to the local RBNB Server by the earlier Data-Source example.

**Sink Example Code**
`Sink mySink = new Sink();` `mySink.OpenRBNBConnection("localhost", "mySink");` `ChannelMap reqmap = new ChannelMap();` `reqmap.Add("mySource/myChan");` `mySink.Request(reqmap, 0., 1., "oldest");` `ChannelMap getmap = mySink.Fetch(1000);` `System.out.println( getmap.GetName(0) ": " + getmap.GetDataAsString(0)[0] );` `.`

3.4 PlugIn Client

An RBNB PlugIn is a special client that connects as a combination source/sink. When a third-party sink requests a channel from the PlugIn, this request (via a ChannelMap object) is sent from the RBNB server to that PlugIn. The PlugIn fills in the answer (puts data) into this request map and returns it, thus dynamically responding to data requests.

A PlugIn client shares the Fetch and Flush methods from the Sink and Source classes, respectively.

`void PlugIn.Register(ChannelMap cmap)`

A PlugIn may (optionally) register the channels that it can provide. These channels become part of the ChannelList for the PlugIn, i.e. they are a means of "advertising" available channels.. Data contained in Registered channels are considered metadata.

If any channels are registered by a PlugIn, only requests for those specific channels will be forwarded by the server to that PlugIn. If no channels are registered by a PlugIn, then any requests to that PlugIn (e.g. "Plugin/anychan") will be forwarded to the PlugIn, that must look at the channel name(s) and decided what to do.

3.4.1 PlugInChannelMap

A PlugInChannelMap is a duel-purpose object. It is fetched to determine a request, and filled in with data to be returned as a response. It is required that the response ChannelMap is the same object as the fetched (request) ChannelMap, as this ties the response to the request.

PlugIns extend regular ChannelMaps to add a few methods unique to their needs.

`double GetRequestStart()`

`double GetRequestDuration()`

The request start and duration indicate the time-slice to be processed. By default, these values constitute the start/duration of the response. That is, there is no need to call PutTime on the response map unless the response map time is different than the request map.

`String GetRequestReference()`

This method returns the type of request being made. The following correspond to the timeRef argument of the corresponding Sink.Request call:

"newest", "oldest", "absolute", "modified", "after"

The following correspond to Sink.Subscribe and Sink.Monitor data requests, respectively:

"subscribe", "monitor"

Note: as of the current release, "subscribe" and "monitor" modes are not supported for PlugIns.

3.4.2 PlugIn Example Code

The following PlugIn code snippet returns a constant value in response to any request.

**PlugIn Example Code**
`PlugIn myPlugIn = new PlugIn();` `myPlugIn.OpenRBNBConnection("localhost", "myPlugIn");` `PlugInChannelMap cmap = myPlugIn.Fetch(1000);` `for (int i=0; i<cmap.NumberOfChannels(); i++) {` `double[] data = { 3.14 };` `cmap.PutDataAsFloat64(i,data);` `}` `myPlugIn.Flush(cmap);` `.`

RBNB WebTurbineTM