VRPN main page

Obtaining VRPN

VRPN Support

Installing and Testing

Compiling and Modifying

Client code

Server code



Logging and Playback

Shared Objects

Clock Synchronization

Coming attractions & suggestions

UNC-specific information

Table of Contents

vrpn_Connection class

The heart of the VRPN library is the vrpn_Connection class. This class dispatches messages locally and across network connections, delivering the messages using callback handlers. Application code does not normally deal directly with the vrpn_Connection class, but rather access it through one or more device classes. Server code will usually create a "listening" instance of this class, and then call its mainloop() function each time through the loop, but will not otherwise deal with the class. It is the device-specific class which deals most intimately with the vrpn_Connection class. Thus, those writing device classes need to thoroughly understand how this class works.

A device-specific class that is derived from one of the existing classes should not have to deal with the vrpn_Connection class to a large extent, since the base class will have handled describing message types and itself as a sender. If the specific class can send messages that the parent class cannot send, then it will need to describe those messages to the connection. If it can receive messages, it will need to register callback handlers for these messages.

All messages in VRPN have a time, a sender and a type associated with them. The time is defined by the sender, and usually corresponds to the time at which the action generating the message occurred (local clock time). For example, the vrpn_Button classes report the time that a button was pressed or released. The sender of a message is a bit of a misnomer; think of this field as being a channel descriptor that describes either the sender or the receiver of a message. For example, this might be "Button0". The type of the message might be "Button Toggle," which tells that a single button was pressed or released. All senders and types are specified using a string name, but actually accessed by a token. Before they can be used, the names must be registered with the connection to get a token.

Initially, there are only two types of vrpn_Connections: one that listens on a socket and one that makes a remote connection to the listening kind. In the future, there are likely to be different classes for shared-memory communication, and for connections that actually deal with only one process. Hopefully, this will have minimal impact on the interface to the class.

Nearly transparent support for clock synchronization across the network is provided by using the vrpn_Synchronized_Connection class (derived from the vrpn_Connection base class). It is fully compatible with the base class but transforms all time stamps into the local time frame. It is highly recommended that you use synchronized connections for all servers and clients (see Clock synchronization in vrpn for more details).

Establishing a VRPN connection

Registering a sender

Registering a message type

Sending a message

Registering a callback handler

A complete example

Forwarding messages