ZStreamMUX Class Reference

Allows one to multiplex independent sessions over a single ZStreamR/ZStreamW pair. More...

List of all members.

Public Types

 errorNone
 The operation succeeded.
 errorAbortLocal
 The operation failed because Abort was called locally.
 errorAbortRemote
 The operation failed because the remote end called Abort.
 errorSendClosed
 Data could not be sent because Close has already been called locally.
 errorReceiveClosed
 The remote end has called Close and all data has been received.
 errorInvalidSession
 The SessionID is either illegal or refers to a non-existent session.
 errorAlreadyListening
 Attempted to listen with a name that is already being listened for.
 errorNotListening
 Attempted to accept or stop listening for a name that was not being listened for.
 errorBadListenName
 The listener name was illegal (currently zero length is the only illegal name).
 errorConnectionDied
 The ZStreamMUX's underlying connection disappeared.
 errorDisposed
 The ZStreamMUX was disposed before the call could complete.
 waitPending
 Used internally.
enum  Error {
  errorNone, errorAbortLocal, errorAbortRemote, errorSendClosed,
  errorReceiveClosed, errorInvalidSession, errorAlreadyListening, errorNotListening,
  errorBadListenName, errorConnectionDied, errorDisposed, waitPending
}

Public Member Functions

void Startup ()
void Shutdown ()
Error Close (SessionID iSessionID)
Error Abort (SessionID iSessionID)
Error Send (SessionID iSessionID, const void *iSource, size_t iCount, size_t *oCountSent)
Error Receive (SessionID iSessionID, void *iDest, size_t iCount, size_t *oCountReceived)
Error CountReceiveable (SessionID iSessionID, size_t &oCountReceivable)


Detailed Description

Allows one to multiplex independent sessions over a single ZStreamR/ZStreamW pair.

Note:
ZStreamMUX is based on some of the ideas from the moribund WebMUX protocol.
ZStreamMUX takes a ZStreamR and a ZStreamW and runs a lightweight protocol over them to support multiple independent sessions. The overall interface is similar to that provided by sockets: Sessions are identified with a SessionID. ZStreamMUX supports up to 512 outbound sessions, for a total of 1024 sessions at once. SessionIDs themselves are 16 bit unsigned integers where bits 0-8 distinguish one session from another, bit 14 (0x4000) is always set and bit 13 (0x2000) indicates whether the session was initiated locally (by calling ZStreamMUX::Open) or remotely (by calling ZStreamMUX::Accept). So valid SessionIDs range from 0x6000 to 0x61FF (for locally-initiated sessions) and from 0x4000 to 0x41FF (for remotely-initiated sessions). Note that zero is never a valid sessionID.

Wire Protocol Summary
S = Session ID (full, possibly of limited range)
T = Session ID (near/far implied, again possibly with a limited range)
W = Near/Far session 1 == sender's notion of far (receiver's near)
                     0 == receiver's notion of far (sender's near)
L = Length of payload that follows
K = Length minus one of payload that follows
P = Listener ID
C = Credit (usually must be multiplied by some constant)
_ = Not determined

Payload
  11WS SLLL   .....
  11WS S111   KKKK KKKK   .....
  11WS S111   1111 1111   KKKK KKKK   KKKK KKKK .....

  101W SSSS   KKKK KKKK   .....
  101W SSSS   1111 1111   KKKK KKKK   KKKK KKKK .....

  100W SSSS   SSSS SLLL   .....
  100W SSSS   SSSS S111   KKKK KKKK   .....
  100W SSSS   SSSS S111   1111 1111   KKKK KKKK   KKKK KKKK   .....

Payload SYN
  01TT TTPP   PPPK KKKK   .....

Add credit
  0011 WTTT   TTCC CCCC
  0010 WTTT   TTTT TTCC   CCCC CCCC

SYN (restricted range for session and listener)
  0001 1TTT   TTPP PPPP

FIN
  0001 01WS   SSSS SSSS

RST
  0001 00WS   SSSS SSSS

SYN (unrestricted range)
  0000 111T   TTTT TTTT   PPPP PPPP

SYNACK
  0000 110T   TTTT TTTT

Define Listener
  0000 1011   PPPP PPPP   LLLL LLLL   .....
  0000 1010   PPPP PPPP   LLLL LLLL   LLLL LLLL   .....

UNUSED
  0000 100_ = 2 different sequences
  0000 0___ = 8 different sequences
  There are ten unused 8 bit sequences available for future use.


Member Enumeration Documentation

enum ZStreamMUX::Error

Enumerator:
errorNone  The operation succeeded.
errorAbortLocal  The operation failed because Abort was called locally.
errorAbortRemote  The operation failed because the remote end called Abort.
errorSendClosed  Data could not be sent because Close has already been called locally.
errorReceiveClosed  The remote end has called Close and all data has been received.
errorInvalidSession  The SessionID is either illegal or refers to a non-existent session.
errorAlreadyListening  Attempted to listen with a name that is already being listened for.
errorNotListening  Attempted to accept or stop listening for a name that was not being listened for.
errorBadListenName  The listener name was illegal (currently zero length is the only illegal name).
errorConnectionDied  The ZStreamMUX's underlying connection disappeared.
errorDisposed  The ZStreamMUX was disposed before the call could complete.
waitPending  Used internally.


Member Function Documentation

void ZStreamMUX::Startup (  ) 

Establish a multiplex connection using fStreamR and fStreamW to communicate. The ZStreamR and ZStreamW need only support the normal facilities, and will typically be the read/write interfaces of a single ZNetEndpoint (which is of course a ZStreamerRW). However it will likely be advantageous to wrap a ZStreamR_Buffered/ZStreamW_Buffered/ZStreamRW_FlushOnRead combo around raw endpoint streams in order to maxmize the size of read/writes made to the OS.

void ZStreamMUX::Shutdown (  ) 

Tear down the multiplexed connection. No exchange of information occurs, we just stop work and dispose working storage. You'll need to use some external technique to ensure that all sessions have finished.

ZStreamMUX::Error ZStreamMUX::Close ( SessionID  iSessionID  ) 

Half-close a session.

Parameters:
iSessionID The session for which we no longer wish to send data. Any call to ZStreamMUX::Send that's already blocked will send all its data. Any subsequent call to Send will fail.
Returns:
  • errorNone: All pending sends have completed and will return errorNone. Any future calls to ZStreamMUX::Send will return errorSendClosed.

  • errorInvalidSession: The session iSessionID does not exist.

  • errorAbortLocal: The session was locally aborted before the half-close could complete.

  • errorAbortRemote: The session was remotely aborted before the half-close could complete.

ZStreamMUX::Error ZStreamMUX::Abort ( SessionID  iSessionID  ) 

Abort a session.

Parameters:
iSessionID The session which we want to shoot in the head. Any pending calls to ZStreamMUX::Send, ZStreamMUX::Receive or ZStreamMUX::Close will return with errorAbortLocal. All resources for the session are released.
Returns:
  • errorNone: All pending sends and receives have been aborted and will return errorAbortLocal.

  • errorInvalidSession: The session iSessionID does not exist.

ZStreamMUX::Error ZStreamMUX::Send ( SessionID  iSessionID,
const void *  iSource,
size_t  iCount,
size_t *  oCountSent 
)

Send data to the remote side of the session.

Parameters:
iSessionID The session over which we wish to send data.
iSource A pointer to the data which we wish to send.
iCount The number of bytes to send.
oCountSent Optional output argument which will be updated with the number of bytes actually sent. If an abort occurs before all data has been sent this will hold the number that was sent prior to the abort.
Returns:
  • errorNone: Data was sent, oCountSent holds some value between 0 and iCount (currently we always send everything).

  • errorInvalidSession: The session iSessionID does not exist.

  • errorAbortLocal, errorAbortRemote: The session was aborted.

ZStreamMUX::Error ZStreamMUX::Receive ( SessionID  iSessionID,
void *  iDest,
size_t  iCount,
size_t *  oCountReceived 
)

Receive data from the remote side of the session.

Parameters:
iSessionID The session from which we wish to receive data.
iDest A pointer to where received data should be placed.
iCount The maximum number of bytes to receive.
oCountReceived Optional output argument which will be updated with the number of bytes actually received.
Returns:
  • errorNone: The size_t referred to by oCountReceived holds the number of bytes that were succesfully received. If less than iCount then it's likely (but not certain) that the remote side has closed the session.

  • errorInvalidSession: The session iSessionID does not exist.

  • errorReceiveClosed: The remote side has called ZStreamMUX::Close, and all data sent prior to that has already been received.

  • errorAbortLocal, errorAbortRemote: The session was aborted.

ZStreamMUX::Error ZStreamMUX::CountReceiveable ( SessionID  iSessionID,
size_t &  oCountReceivable 
)

Get the number of bytes that can be read without blocking.

Parameters:
iSessionID The session from which we wish to receive data.
oCountReceivable On success this will hold the number of bytes that could be retrieved by a call to ZStreamMUX::Receive without blocking.
Returns:
  • errorNone

  • errorInvalidSession: The session iSessionID does not exist.

  • errorReceiveClosed: The remote side has called ZStreamMUX::Close, and all data sent prior to that has already been received.


The documentation for this class was generated from the following files:
Generated on Thu Jul 26 11:22:02 2007 for ZooLib by  doxygen 1.4.7