View of /trunk/uia/sst/doc/mainpage.dox

/* doxygen index page */
/** @mainpage SST Library Documentation

Structured Stream Transport, or SST, is a new transport protocol
designed to address the needs of modern applications
that need to juggle many asynchronous communication activities in parallel,
such as downloading different parts of a web page simultaneously
and playing multiple audio and video streams at once.
This documentation is for libsst,
a library that implements the SST protocol in user space.
(Kernel-level implementations of SST are certainly possible
but do not exist yet.)
Please see http://pdos.csail.mit.edu/uia/sst/
for more information on the SST protocol itself.

This library implementation of SST is written in C++ 
and makes heavy use of Trolltech's Qt 4 framework
for convenience and portability across platforms.
You can use libsst in applications not based on Qt 4,
but in this case you will still have to link your application
with the QtCore and QtNet libraries along with libsst
(QtGui is not necessary),
and re-implement the QAbstractEventDispatcher class
to provide the basic asynchronous event services that libsst needs,
such as registering the UDP socket descriptors that SST uses
with your main event loop.

Here is a quick summary of how to use libsst for communication
in your application:

-#	First create a instance of the SST::Host class
	to hold per-host state.
	You can run multiple virtualized copies of SST in one process
	for simulation or other purposes by creating several Host objects.
-#	Set up a server to accept incoming connections,
	by creating an instance of SST::StreamServer
	and calling its SST::StreamServer::listen() method.
	In place of the 16-bit port numbers used by TCP and UDP,
	you will need to provide a service name and protocol name
	for dispatching incoming clients to different servers.
-#	To initiate an outgoing connection from a client to the server,
	create an SST::Stream object
	and call SST::Stream::connectTo().
	You can indicate the target host in two ways:
	-	To create an insecure, TCP-style connection,
		call SST::Ident::fromIpAddress()
		to create an SST endpoint identifier (EID)
		representing the target's IP address and UDP port number,
		and pass this identifier to SST::Stream::connectTo()
		along with the desired SST service and protocol names.
	-	To establish a secure connection
		using strong cryptographic authentication and encryption,
		you'll need the target host's cryptographic EID,
		which can be obtained
		by calling SST::IdentHostState::hostIdent()
		on that host's SST::Host object.
		On the client, call SST::Stream::connectTo()
		with this cryptographic EID,
		the desired service and protocol names,
		and a second EID generated by SST::Ident::fromIpAddress() above
		as a "location hint" SST can use to find the target host.
		The location hint is unnecessary
		if you use SST's registration protocol
		or the (not yet integrated) UIA routing protocol.

The SST protocol and libsst prototype implementation
were developed as part of the
Unmanaged Internet Architecture (UIA) project at MIT;
please see http://pdos.csail.mit.edu/uia/ for more information.

*/