Documentation for the EiToolkit

If you want to develop with the toolkit, you need SVN access since there have not been any releases yet. Please refer to the EiToolkit page to see how to gain SVN access.

General

If you want to connect the toolkit to some data source or sink, write a stub that translates UDP messages to your own data and/or back.

If you want to use data provided by or received by existing components, write an application that uses works on UDP messages.

Also see toolkitclasses.doc for a quick overview on the involved interfaces and classes.

Scripts and Templates

There is a SampleUDPListenerStub that can be copied. Using the Perl script givename.pl you can give the project and the stub the name you wish them to have. The SampleUDPListenerParticleStub additionally provides code to talk with TecO Particles.

In the scripts directory, there are small Perl scripts that allow converting solution and project files between Visual Studio .NET 2003 and 2005. Note that not all parameters will be converted.

Logging and Debugging

For debugging and monitoring purposes, there are the UDPGenerator and UDPListener programs that can be found in comm/udp/test/. They are command line applications that can be used to generate messages and monitor sent messages, respectively.

Two applications found in applications/ are used to log messages sent. The LoggingApp writes all messages to a log file. The standard PacketFormatter is used for serialisation. The IDs of senders that should be logged can be specified. The LogReaderApp reads a log created by the LoggingApp and resends those messages to the system. Currently, timing of the packets is not taken into account.

Streaming

The messaging system is not exactly meant to be used for streaming a lot of data in real time. For such purposes, the messaging service can be used to make information available about where such streaming data is available.

One available implementation is based on RTP (Real-time Transport Protocol). It uses the open implementation called JRTPLIB; a version can be found in third_party/jrtplib/. To setup a stream and read it, controlled by the messaging system, you only need to use the two stubs RTPStreamerStub and RTPListenStub.

  • RTPStreamInfoEI: Found in comm/rtp/. It encapsulates all information necessary to describe a stream (except its ID). If you want to provide a stream, e.g., you will have call SetDestinationIp and SetDestinationPort.

  • RTPStreamerStub: This is a stub used to stream data. The stream is identified with a unique ID that must be specified. The stub offers information about its stream with a specific message (SendRTPInfo()). You have to specify parameters of the stream through the RTPStreamInfoEI class described above. There are 2 possibilities to use this stub:
    • Inheritance: Create a class that inherits from RTPStreamerStub and overwrites the method RTPStreamerStub::GetNextPacket(void **data, unsigned int *dataLen). This method is called whenever a new packet is needed to be sent. The RTPStreamerStub provides an example implementation.
    • Use: Create an instance of RTPStreamerStub and implement a class that implements StreamProvider found in comm/stream/. The only method it needs is GetNextPacket(void **data, unsigned int *dataLen). This method is called whenever a new packet is needed to be sent. The RTPStreamerStub provides an example implementation. Then use SetStreamProvider(StreamProvider *streamProvider) to set your provider.

  • RTPListenStub: This is a stub used to receive streaming data from a stream with a specific ID. The stub gets the information about the stream by requesting it (SendStreamRequest) and waiting for the stream information message which is parsed into an RTPStreamInfoEI instance described above. There are 2 possibilities to use this stub:
    • Inheritance: Create a class that inherits from RTPListenStub and overwrites the method RTPListenStub::OnStreamData(RTPPacket *packet). This method is called whenever a new packet has been received. The RTPListenStub provides an example implementation.
    • Use: Create an instance of RTPListenStub and implement a class that implements StreamListener found in comm/stream/. The only method it needs is RTPStreamerStub::OnStreamData(RTPPacket *packet). This method is called whenever a new packet is needed to be sent. The RTPListenerStub provides an example implementation. Then use AddStreamListener(StreamListener *listener) to add your class as listener.

System Implementation

Stub (stubs/)

Stubs are proxies that connect components to the messaging system. A Winamp control stub, e.g., would take (UDP) messages in a certain format as input, translate them and pass the commands to Winamp. The minimum set of methods a stub must support are (Stub.h):

  • std::string GetName(): A unique ID identifying this stub; used as sender and receiver ID
  • void Start(): This method will be called to activate the stub
  • void Stop(): This method will be called to deactivate the stub

System Access (utils/Properties)

utils/Properties.h provides several static methods to access central components of the system. This includes:

  • PacketReceiver *GetPacketReceiver(): You can register a PacketObserver to the PacketReceiver class which is notified when any event packet is passed through the messaging system
  • PacketSender *GetPacketSender: You can use the SendPacket(const Packet *sendPacket) method to send a packet to the messaging system
  • PacketFormatter* GetPacketFormatter(): The PacketFormatter is responsible to write and parse raw string to / from message packets, i.e. implement the protocol used for sending data

  • UseStandards(): Sets default values for packet senders, receivers, ports, formatters, etc. and starts them if necessary
  • StopStandards(): Stops all running packet senders, receivers, etc.

  • SetXXX(): see also next item
  • UseStandardXXX(): If you want more control, you can also set the packet sender implementation etc. on your own using SetXXX() methods or use the standard implementation using UseStandardXXX().

Messaging

Messages are sent using packets. the standard implementation uses UDP.

  • Packet: One information unit. Uses a PacketFormatter to serialise to or generate itself from a raw string
  • PacketEvent: Encapsulates a Packet and a time stamp specifying when the packet was sent.

  • PacketFormatter: Provides method to serialise a packet or to create one by parsing a string

  • PacketReceiver: Used to receive messages. It possibly bundles a set of =PacketReceiverImpl=s that may implement different protocols etc.

  • PacketSender: Used to send messages. It possibly bundles a set of =PacketSenderImpl=s that may implement different protocols etc.

Main Method of Stubs

When using the messaging system and stubs in general, a few things must be setup correctly. The easiest way of doing this is to use auxiliary methods in utils/Properties and set a few preprocessor options according to your demand:

  • define _NO_LISTENERS if you don't need to listen to (UDP) packets from the messaging system, i.e. for stubs that only pass data from a component to the system
  • define _NO_SENDERS if you don't need to send (UDP) packets to the messaging system
  • define _NO_PARTICLE_COMM if you don't need Particle communication

Then the code needed to get everything going is very small:

Properties::UseStandards();

MyStub stub;

stub.Start();

... // if the stub is not blocking, could use sth like while (_getch() 27);=

stub.Stop();

Properties.StopStandards();

Other Classes

utils/Helper.h provides some general auxiliary methods

utils/Exceptions.h is a collection of specialised exceptions

-- PaulHolleis - 12 Apr 2006
Topic revision: r3 - 23 Jun 2008, PaulHolleis
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Medieninformatik-Wiki? Send feedback