Entity providers are responsible for processing raw data and converting it into entity objects. The entities can be manipulated in a generic way, regardless of the data source they originated from.
When combined with stream plugins, an entity provider can process data transparently, regardless of the data source (e.g., network, e-mail, hard disk, polled directory, etc.). The AGI catalog of entity providers is constantly growing, so before writing your own you may want to contact AGI to see if a particular feed type is already supported.
Implementing your own entity provider is as simple as implementing a Microsoft COM object. The minimum interfaces needed for implementation are, IAgRtProvideEntities (the main interface for an entity provider plugin), and IAgRtProvideEntitiesEvents (in order to execute events when the provider is started and stopped). Optionally, you can implement IAgAttrConfig in order to easily present configuration options to end users which can be saved and loaded along with the rest of their RT3 settings. Finally, you can also implement IAgRtProvideEntitiesFromStream in order to take advantage of stream plugins.
While it is entirely possible to code an entity provider to read data from a single source (e.g., a file on disk or over a specific TCP/IP connection), it is better to separate the data parsing done by the entity provider from the actual data acquisition; a stream plugin fills this niche. By having your entity provider implement the IAgRtUseStream interface, it no longer has to worry about where the data is coming from, but instead only how to parse that data and convert it into entities. In addition, using stream plugins you can add new ways of accessing a stream without any modifications to the original entity provider. Furthermore, if a new stream type is implemented - for example, a TCP/IP connection stream - it immediately becomes available for use by all existing entity providers. This makes it possible for users to implement even the most obscure data access procedures - such as polling a directory over ftp every few minutes. While there are some situations where hard coding an entity provider is the best way to go, it is generally good practice to write in for use with streams when possible.
Implementing your own stream plugin is easy; there are only two interfaces necessary. The first is IAgRtStreaminterface, the second is IAgAttrConfig (for publishing the configuration options for your stream).
While stream plugins are useful if written properly, it is often easier to simply implement your initial entity provider plugin without them and add the capbility later if needed. This is especially true for .NET based plugins which can make use of the .NET Framework's immense library of available StreamReader classes.
Suppose that you have an entity provider plugin called MyProvider. The basic steps for creating an instance of your provider and getting it started are:
//Create the Rt3 application class, which
is a singleton and can always be created on the fly as needed.
AgRt3Application Rt3 = new AgRt3Application();
//Register MyProvider
MyProviderClass MyProvider = new MyProviderClass() //Create and
register MyProvider
Rt3.RegisterEntityProvider(MyProvider as IAgRtProvideEntities);
MyProvider.InstanceName = "MyName";
//Create a new TCP/IP Stream and assign it to the Provider
AgRtTCPIPStream MyStream = new AgRtTCPIPStream();
MyStream.HostName = "mystream.myserver.com";
MyStream.Port = 7012;
MyProvider.Stream = MyStream as IAgRtStream;
//Start the Provider
MyProvider.Start();
Inside the entity provider implementation itself, it opens and reads data from the stream. It has no concept of where the data is originating. The following example requests 80 bytes of data at a time and parses it.
Stream.Open();
while(this._bActive)
{
//Read a Message
Array byteData = Stream.Read(80) as
Array;
//Turns the bytes into a string since this
is a text based format
string Message = "";
foreach (SByte i in byteData)
{
Message +=
System.Convert.ToChar(i);
}
//Parse and Process Message
}
Stream.Close();
Fully documented sample entity provider and stream plugins are located in <STK install folder>Help/RT3/Samples. When you are ready to start testing and debugging your plugin, go to Registering an RT3 Plugin. If you want to add a custom user interface, see Implementing a Custom User Interface for an RT3 Plugin.
STK Programming Interface 11.0.1