QSocketSession Class Reference
[Classes to further consolidate Qt as the ultimate cross platform framework.]

Base utility class for dealing with Geddei socket connections. More...

#include <qsocketsession.h>

List of all members.

Public Member Functions

 QSocketSession (QSocketDevice *sd)
template<>
void safeReceiveWordArray (uint32_t *t, const uint32_t size)
template<>
void safeReceiveWordArray (int32_t *t, const uint32_t size)
template<>
void safeReceiveWordArray (float *t, const uint32_t size)
 ~QSocketSession ()
Basic methods for use anytime.
These methods are basic and take no notice of the word byte-ordering differences between hosts. they may be used before (and after) handshaking.

void ack (const bool sign=true)
void close ()
const bool isOpen ()
const uchar receiveByte ()
const bool receiveChunk (uchar *buffer, const uint size, const uint timeOut)
void receiveChunk (uchar *buffer, const uint size)
void sendByte (const uchar c)
void sendChunk (const uchar *buffer, const uint size)
const bool waitForAck (const uint timeOut, bool *ackType=0)
const bool waitForAck (bool *ackType=0)
Advanced methods for use after handshaking.
These are advanced methods that take notice of any differences between the two hosts byte ordering, altering data if necessary to compensate.

They must only ever be used after a successful handshake.

For brevity 32bit word has been shortened to Word in the names. Though the type given is an int, floats may be used in their place.

void handshake ()
void handshake (const bool opposite)
const QCString receiveString ()
template<typename T>
const T safeReceiveWord ()=0
template<typename T>
void safeReceiveWordArray (T *t, const uint32_t size)=0
void safeSendWord (const uint32_t i)
void safeSendWord (const int32_t i)
void safeSendWord (const float i)
void safeSendWordArray (const uint32_t *i, const uint size)
void safeSendWordArray (const int32_t *i, const uint size)
void safeSendWordArray (const float *i, const uint size)
const bool sameByteOrder () const
void sendString (const QCString &s)


Detailed Description

Base utility class for dealing with Geddei socket connections.

Author:
Gav Wood <gav@cs.york.ac.uk>
QSocketSession provides a suitable interface to TCP sockets for more high-level uses. Through handshaking, it can determine if both hosts share the same byte ordering for words, and through its "safe" methods can alter transmissions accordingly transparently to the developer.

It also provides other methods to listen on timeouts and and send higher level data such as QCStrings.

Communication methods do not return a status; to check if the data was sent or received correctly, just check the value of isOpen() after the relevant call.

This is not thread-safe or reentrant.


Constructor & Destructor Documentation

QSocketSession::QSocketSession ( QSocketDevice *  sd  ) 

Basic constructor.

Parameters:
sd The QSocketDevice this session will use to do its communications. It will adopt this and thus destroy it when this object gets destroyed. Deleting sd yourself will result in a memory error.

QSocketSession::~QSocketSession (  ) 

Safe destructor.


Member Function Documentation

const bool QSocketSession::isOpen (  )  [inline]

Determine if the current connection is open.

Returns:
true if the current connection is open (i.e. connected).

void QSocketSession::close (  ) 

Close the current connection.

void QSocketSession::ack ( const bool  sign = true  )  [inline]

Send an acknowledgement byte through the connection. This matches the waitForAck() method.

Parameters:
sign The sign of the acknowledgement. This is returned from the matching waitForAck() method on the other side of the connection.
See also:
waitForAck()

void QSocketSession::sendByte ( const uchar  c  )  [inline]

Sends a byte value down the connection. Matches receiveByte().

Parameters:
c The value of the byte to be sent.
See also:
receiveByte()

void QSocketSession::sendChunk ( const uchar *  buffer,
const uint  size 
)

Send a number of bytes down the connection as one single entity. Matches receiveChunk().

Parameters:
buffer An array of bytes to be sent.
size The size of the array.
See also:
receiveChunk()

const uchar QSocketSession::receiveByte (  )  [inline]

Receive a single byte from the connection. Matches sendByte().

This will block until either the connection fails or the byte is received.

Returns:
A byte read from the connection. 0 if the connection is not open by the time this returns.
See also:
sendByte()

void QSocketSession::receiveChunk ( uchar *  buffer,
const uint  size 
)

Receive some number of bytes from the connection. The number received is stated in size.

This will block until either the connection fails or the number of bytes is received.

Parameters:
buffer The array of bytes that the data is to be written into. Must be at least size big.
size The number of bytes to be read from the connection.
See also:
sendChunk()

const bool QSocketSession::receiveChunk ( uchar *  buffer,
const uint  size,
const uint  timeOut 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Receive some number of bytes from the connection. The number received is stated in size.

This will block until either the connection fails or the number of bytes is received, or the timeout timeOut is reached.

Parameters:
buffer The array of bytes that the data is to be written into. Must be at least size big.
size The number of bytes to be read from the connection.
timeOut Number of milliseconds to wait before giving up.
Returns:
true if all was received ok, false if there was a timeout or problem with the connection.
See also:
sendChunk()

const bool QSocketSession::waitForAck ( bool *  ackType = 0  ) 

Block until the next communication is received. It is interpreted as an acknowledgement sent by ack().

This is one of the few receiving methods that provides you with a return value which determines if the communication went ok.

Parameters:
ackType If non-0, the sign of the send acknowledgement is populated into boolean here.
Returns:
true if the ack was received ok, false if there was a problem with the connection.
See also:
ack()

const bool QSocketSession::waitForAck ( const uint  timeOut,
bool *  ackType = 0 
)

Block until the next communication is received. It is interpreted as an acknowledgement sent by ack().

This will block until either the connection fails or the number of bytes is received, or the timeout timeOut is reached.

Parameters:
timeOut Number of milliseconds to wait before giving up.
ackType If non-0, the sign of the send acknowledgement is populated into boolean here.
Returns:
true if the ack was received ok, false if there was a timeout or problem with the connection.
See also:
ack()

void QSocketSession::handshake ( const bool  opposite  ) 

Conduct a handshake operation. This should be done when ever possible at the start of a connection.

It is always best to use this when ever possible. On asymmetric connections it is easy to make sure that you can guarantee both sides' opposite value will be different. Otherwise you may need to use the overloaded version.

Parameters:
opposite This must be true on one side of the handshake and false on the other. It won't work otherwise.

void QSocketSession::handshake (  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Conduct a handshake operation. This should be done when ever possible at the start of a connection.

This assumes that srand() has been set up with a REALLY unpredictable value. If not, this method may loop infinitely, causing your program to crash.

Only ever use this on symmetric connections where either node has been properly seeded (with something unique like pid, datetime and ip).

const bool QSocketSession::sameByteOrder (  )  const [inline]

Determine if the two hosts share the same word byte-ordering.

Returns:
true if they share the same byte-ordering.

void QSocketSession::safeSendWord ( const float  i  )  [inline]

Send a single word down the connection. This can be one of int, float or uint. Undefined action for any other types used.

Parameters:
i The word to be sent down.
See also:
safeReceiveWord()

void QSocketSession::safeSendWordArray ( const float *  i,
const uint  size 
) [inline]

Send a number of words down the connection. These can be one of int, float or uint. Undefined action for any other types used.

Parameters:
i The array of words. Must be at least size big.
size The number of values to be sent.
See also:
safeReceiveWordArray()

const uint32_t QSocketSession::safeReceiveWord (  )  [pure virtual]

Receive a single word from the connection. The word type must be given as the template parameter and may be one of float, int32_t or uint32_t. This must correspond to the type sent with safeSendWord().

This will block until either the connection fails or the number of words is received.

Returns:
The word received from the connection. Undefined if isOpen() returns false, or if the corresponding word sent was a float.
See also:
safeSendWord()

template<typename T>
void QSocketSession::safeReceiveWordArray ( T *  t,
const uint32_t  size 
) [pure virtual]

Receive a number of words from the connection. The word type may be one of float, int or uint. This must correspond to the type sent with safeSendWord().

This will block until either the connection fails or the number of words is received.

Parameters:
i The array of words that the data is to be written into. Must be at least size big.
size The number of words to be read from the connection.
See also:
safeSendWordArray()

void QSocketSession::sendString ( const QCString &  s  ) 

Send a string value down the connection.

Parameters:
s The QCString value to be sent.

const QCString QSocketSession::receiveString (  ) 

Receive a string value from the connection.

This will block until either the connection fails or the number of bytes is received.

Returns:
The sent string.


The documentation for this class was generated from the following files:
Generated on Thu Jul 13 06:56:35 2006 for Exscalibar by  doxygen 1.4.7