SST::Stream Class Reference

This class represents an SST stream. More...

#include <stream.h>

List of all members.

Public Types
enum	ShutdownModeFlag { Read = 1, Write = 2, Close = 3, Reset = 4 }
Signals
void	readyReadMessage ()
	Emitted when a message/record marker arrives in the incoming byte stream ready to be read.
void	newSubstream ()
	Emitted when we receive an incoming substream while listening.
void	readyReadDatagram ()
	Emitted when a queued incoming substream may be read as a datagram.
void	linkUp ()
	Emitted when the stream establishes live connectivity upon first connecting, or after being down or stalled.
void	linkDown ()
	Emitted when link connectivity for the stream has been lost.
void	receiveBlocked ()
	Emitted when incoming data has filled our receive window.
void	reset (const QString &errorString)
	Emitted when the stream is reset by either endpoint.
void	error (const QString &errorString)
	Emitted when an error condition is detected on the stream.
Public Member Functions
	Stream (Host *host, QObject *parent=NULL)
	Create a new Stream instance.
bool	connectTo (const QByteArray &dstid, const QString &service, const QString &protocol, const Endpoint &dstep=Endpoint())
	Connect to a given service and protocol on a remote host.
bool	connectTo (const Ident &dstid, const QString &service, const QString &protocol, const Endpoint &dstep=Endpoint())
	Connect to a given service and protocol on a remote host.
void	disconnect ()
	Disconnect the stream from its current peer.
bool	isConnected ()
	Returns true if the Stream is logically connected and usable for data read/write operations.
qint64	bytesAvailable () const
	Determine the number of bytes currently available to be read via readData().
bool	hasBytesAvailable () const
	Returns true if at least one byte is available for reading.
virtual qint64	readData (char *data, qint64 maxSize)
	Read up to maxSize bytes of data from the stream.
int	pendingMessages () const
	Returns the number of complete messages currently available for reading.
bool	hasPendingMessages () const
	Returns true if at least one complete message is currently available for reading.
qint64	pendingMessageSize () const
	Determine the number of message/record markers that have been received over the network but not yet read.
qint64	readMessage (char *data, int maxSize)
	Read a complete message all at once.
QByteArray	readMessage (int maxSize=1<< 30)
	Read a complete message into a new QByteArray.
bool	atEnd () const
	Returns true if all data has been read from the stream and the remote host has closed its end: no more data will ever be available for reading on this stream.
qint64	writeData (const char *data, qint64 size)
	Write data bytes to a stream.
qint64	writeMessage (const char *data, qint64 size)
	Write a message to a stream.
qint64	writeMessage (const QByteArray &msg)
	Write a message to a stream.
int	readDatagram (char *data, int maxSize)
QByteArray	readDatagram (int maxSize=1<< 30)
int	writeDatagram (const char *data, int size)
int	writeDatagram (const QByteArray &dgram)
bool	hasPendingDatagrams () const
qint32	pendingDatagramSize () const
Stream *	openSubstream ()
	Initiate a new substream as a child of this stream.
void	listen ()
	Listen for incoming substreams on this stream.
bool	isListening () const
	Returns true if this stream is set to accept incoming substreams.
Stream *	acceptSubstream ()
	Accept a waiting incoming substream.
QByteArray	localHostId ()
	Returns the endpoint identifier (EID) of the local host as used in connecting the current stream.
QByteArray	remoteHostId ()
	Returns the endpoint identifier (EID) of the remote host to which this stream is connected.
bool	isLinkUp ()
	Returns true if the Stream is logically connected and network connectivity is currently available.
void	setPriority (int pri)
	Set the stream's transmit priority level.
int	priority ()
	Returns the stream's current priority level.
void	shutdown (ShutdownMode mode)
	Begin graceful or forceful shutdown of the stream.
void	close ()
	Gracefully close the stream for both reading and writing.
void	dump ()
	Dump the state of this stream, for debugging purposes.
Protected Member Functions
void	setError (const QString &errorString)
Friends
class	AbstractStream
class	BaseStream
class	StreamServer

---

Detailed Description

This class represents an SST stream.

This is the primary high-level class that client applications use to communicate over the network via SST. The class provides standard stream-oriented read/write functionality via the methods in its QIODevice base class, and adds SST-specific methods for controlling SST streams and substreams.

To initiate an outgoing "top-level" SST stream to a remote host, the client application creates a Stream instance and then calls connectTo(). To initiate a sub-stream from an existing stream, the application calls openSubstream() on the parent stream.

To accept incoming top-level streams from other hosts the application creates a StreamServer instance, and that class creates Stream instances for incoming connections. To accept new incoming substreams on existing streams, the application calls listen() on the parent stream, and upon arrival of a newSubstream() signal the application calls acceptSubstream() to obtain a Stream object for the new incoming substream.

SST uses service and protocol names in place of the port numbers used by TCP and UDP to differentiate and select among different application protocols. A service name represents an abstract service being provided: e.g., "Web", "File", "E-mail", etc. A protocol name represents a concrete application protocol to be used for communication with an abstract service: e.g., "HTTP 1.0" or "HTTP 1.1" for communication with a "Web" service; "FTP", "NFS v4", or "CIFS" for communication with a "File" service; "SMTP", "POP3", or "IMAP4" for communication with an "E-mail" service. Service names are intended to be suitable for non-technical users to see, in a service manager or firewall configuration utility for example, while protocol names are primarily intended for application developers. A server can support multiple distinct protocols on one logical service, for backward compatibility or functional modularity reasons for example, by registering to listen on multiple (service, protocol) name pairs.

See also:

StreamServer

---

Constructor & Destructor Documentation

Stream::Stream (  Host *  host, QObject *  parent = NULL )

Create a new Stream instance. The Stream must be connected to a remote host via connectTo() before it can be used for communication. Parameters: host  the Host instance containing hostwide SST state. parent  the Qt parent for the new object. The Stream will be automatically destroyed when its parent is destroyed.

---

Member Function Documentation

Stream * Stream::acceptSubstream (   )

Accept a waiting incoming substream. By default, the new Stream object's Qt parent object is the parent Stream object on which acceptSubstream() was called, so the substream will automatically be deleted if the application deletes the parent stream. The application may re-parent the new Stream object using QObject::setParent(), however, in which case the substream may outlive its parent. Returns NULL if no incoming substreams are waiting.

bool Stream::atEnd (   )  const

Returns true if all data has been read from the stream and the remote host has closed its end: no more data will ever be available for reading on this stream.

qint64 Stream::bytesAvailable (   )  const

Determine the number of bytes currently available to be read via readData(). Note that calling readData() with a buffer this large may not read all the available data if there are message/record markers present in the read stream.

void SST::Stream::close (   )  [inline]

Gracefully close the stream for both reading and writing. Still-buffered written data continues to be sent, but any further data received from the other side is dropped.

bool SST::Stream::connectTo (  const Ident &  dstid, const QString &  service, const QString &  protocol, const Endpoint &  dstep = Endpoint() )

Connect to a given service and protocol on a remote host. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Stream::connectTo (  const QByteArray &  dstid, const QString &  service, const QString &  protocol, const Endpoint &  dstep = Endpoint() )

Connect to a given service and protocol on a remote host. The stream logically goes into the "connected" state immediately (i.e., isConnected() returns true), and the application may start writing to the stream immediately, but actual network connectivity may not be established until later or not at all. Either during or some time after the connectTo() call, SST emits the linkUp() signal to indicate active connectivity, or linkDown() to indicate connectivity could not be established. A linkDown() signal is not necessarily fatal, however: unless the application disconnects or deletes the Stream object, SST will continue attempting to establish connectivity and emit linkUp() if and when it eventually succeeds. If the stream is already connected when connectTo() is called, SST immediately re-binds the Stream object to the new target but closes the old stream gracefully in the background. Similarly, SST closes the stream gracefully in the background if the application just deletes a connected Stream object. To close a stream forcefully without retaining internal state, the application may explicitly call shutdown(Reset) before re-connecting or deleting the Stream object. Parameters: dstid  the endpoint identifier (EID) of the desired remote host to connect to. The destination may be either a cryptographic EID or a non-cryptographic legacy address as defined by the Ident class. service  the service name to connect to on the remote host. protocol  the application protocol name to connect to. dstep  an optional location hint for SST to use in attempting to contact the host. If the dstid parameter is a cryptographic EID, which is inherently location-independent, SST may need a location hint to find the remote host if this host and the remote host are not currently registered at a common registration server, for example. This parameter is not needed if the dstid is a non-cryptographic legacy address. Returns: true if successful, false if an error occurred. See also: Ident

void Stream::disconnect (   )

Disconnect the stream from its current peer. This method immediately returns the stream to the unconnected state: isConnected() subsequently returns false. If the stream has not already been shutdown, however, SST gracefully closes the stream in the background as if with shutdown(Close). See also: shutdown()

void SST::Stream::error (  const QString &  errorString  )  [signal]

Emitted when an error condition is detected on the stream. Link stalls or failures are not considered error conditions.

bool Stream::isConnected (   )

Returns true if the Stream is logically connected and usable for data read/write operations. The return value from this method changes only as a result of the application's calls to connectTo() and disconnect(). Logical connectivity does not imply that the network link is live: the underlying link may go up or down repeatedly during the logical lifetime of the stream.

bool Stream::isLinkUp (   )

Returns true if the Stream is logically connected and network connectivity is currently available. SST emits linkUp() and linkDown() signals when the underlying link connectivity state changes.

void SST::Stream::linkDown (   )  [signal]

Emitted when link connectivity for the stream has been lost. SST may emit this signal either due to a timeout or due to detection of a link- or network-level "hard" failure. The link may come back up sometime later, however, in which case SST emits linkUp() and stream connectivity resumes. If the application desires TCP-like behavior where a connection timeout causes permanent stream failure, the application may simply destroy the stream upon receiving the linkDown() signal.

QByteArray Stream::localHostId (   )

Returns the endpoint identifier (EID) of the local host as used in connecting the current stream. Only valid if the stream is connected.

void SST::Stream::newSubstream (   )  [signal]

Emitted when we receive an incoming substream while listening. In response the client should call acceptSubstream() in a loop to accept all queued incoming substreams, until acceptSubstream() returns NULL.

Stream * Stream::openSubstream (   )

Initiate a new substream as a child of this stream. This method completes without synchronizing with the remote host, and the client application can use the new substream immediately to send data to the remote host via the new substream. If the remote host is not yet ready to accept the new substream, SST queues the new substream and any data written to it locally until the remote host is ready to accept the new substream. By default, the new Stream object's Qt parent object is the parent Stream object on which openSubstream() was called, so the substream will automatically be deleted if the application deletes the parent stream. The application may re-parent the new Stream object using QObject::setParent(), however, without affecting the function of the substream. Returns: a Stream object representing the new substream.

qint64 Stream::pendingMessageSize (   )  const

Determine the number of message/record markers that have been received over the network but not yet read. XXX This function may need to be removed from the API, since the size of a large message will be unknown until the entire message has already come in, which it may not if receiver flow control is working.

qint64 Stream::readData (  char *  data, qint64  maxSize )  [virtual]

Read up to maxSize bytes of data from the stream. This method only returns data that has already been received and is waiting to be read: it never blocks waiting for new data to arrive on the network. A single readData() call never crosses a message/record boundary: if it encounters a record marker in the incoming byte stream, it returns only the bytes up to that record marker and leaves any further data for subsequent readData() calls. Parameters: data  the buffer into which to read. This parameter may be NULL, in which case the data read is simply discarded. maxSize  the maximum number of bytes to read. Returns: the number of bytes read, or -1 if an error occurred. Returns zero if there is no error condition but no bytes are immediately available for reading.

QByteArray SST::Stream::readMessage (   )

Read a complete message into a new QByteArray. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Parameters: maxSize  the maximum size of the message to read; any bytes in the message beyond this are discarded. Returns: the message received, or an empty QByteArray if an error occurred or there are no messages to receive.

qint64 Stream::readMessage (  char *  data, int  maxSize )

Read a complete message all at once. Reads up to the next message/record marker (or end of stream). If no message/record marker has arrived yet, just returns without reading anything. If the next message to be read is larger than maxSize, this method simply discards the message data beyond maxSize. Parameters: data  the buffer into which to read the message. maxSize  the maximum size of the message to read. Returns: the size of the message read, or -1 if an error occurred. Returns zero if there is no error condition but no complete message is available for reading.

void SST::Stream::readyReadDatagram (   )  [signal]

Emitted when a queued incoming substream may be read as a datagram. This occurs once the substream's entire data content arrives and the remote peer closes its end while the substream is queued, so that the entire content may be read at once via readDatagram(). (XXX or perhaps when an entire first message/record arrives?) Note that if the client wishes to read datagrams using this signal, the client must ensure that the parent's maximum receive window is large enough to hold any incoming datagram that might arrive, or else monitor the parent stream's receiveBlocked() signal and grow the receive window to accommodate large datagrams.

void SST::Stream::readyReadMessage (   )  [signal]

Emitted when a message/record marker arrives in the incoming byte stream ready to be read. This signal indicates that a complete record may be read at once. If the client wishes to delay the reading of any data in the message or record until this signal arrives, to avoid the potential for deadlock the client must ensure that the stream's maximum receive window is large enough to accommodate any message or record that might arrive - or else monitor the receiveBlocked() signal and dynamically expand the receive window as necessary.

void SST::Stream::receiveBlocked (   )  [signal]

Emitted when incoming data has filled our receive window. When this situation occurs, the client must read some queued data or else increase the maximum receive window before SST will accept further incoming data from the peer. Every single byte of the receive window might not be utilized when the receive process becomes blocked in this way, because SST does not fragment packets just to "top up" a nearly empty receive window: the effective limit may be as low as half the specified maximum window size.

void Stream::setPriority (  int  pri  )

Set the stream's transmit priority level. When the application has multiple streams with data ready to transmit to the same remote host, SST uses the respective streams' priority levels to determine which data to transmit first. SST gives strict preference to streams with higher priority over streams with lower priority, but it divides available transmit bandwidth evenly among streams with the same priority level. All streams have a default priority of zero on creation. Parameters: pri  the new priority level for the stream.

void Stream::shutdown (  ShutdownMode  mode  )

Begin graceful or forceful shutdown of the stream. To close the stream gracefully in either or both directions, specify Read, Write, or Read|Write for the mode argument. Closing the stream in the Write direction writes the end-of-stream marker to our end of the stream, indicating to our peer that no more data will arrive from us. Closing the stream in the Read direction discards any data waiting to be read or subsequently received from the peer. Specify a mode of Reset to shutdown the stream immediately; written data that is still queued or in transit may be lost. Parameters: dir  which part of the stream to close: either Read, Write, Close (same as Read|Write), or Reset.

qint64 Stream::writeData (  const char *  data, qint64  size )

Write data bytes to a stream. If not all the supplied data can be transmitted immediately, it is queued locally until ready to transmit. Parameters: data  the buffer containing the bytes to write. size  the number of bytes to write. Returns: the number of bytes written (same as the size parameter), or -1 if an error occurred.

qint64 SST::Stream::writeMessage (  const QByteArray &  msg  )  [inline]

Write a message to a stream. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Parameters: msg  a QByteArray containing the message to write.

qint64 Stream::writeMessage (  const char *  data, qint64  size )

Write a message to a stream. Writes the data in the supplied buffer followed by a message/record marker. If some data has already been written via writeData(), then that data logically forms the "head" of the message and the data presented to writeMessage() forms the "tail". Thus, a large message can be written incrementally by calling writeData() any number of times followed by a call to writeMessage() to finish the message. A message/record marker is written at the current position even if this method is called with no data (size = 0). Parameters: data  the buffer containing the message to write. size  the number of bytes of data to write. Returns: the number of bytes written (same as the size parameter), or -1 if an error occurred.

---

The documentation for this class was generated from the following files:

• /Users/baford/proj/netsteria/sst/lib/stream.h
• /Users/baford/proj/netsteria/sst/lib/stream.cc

---