#include <qsocketsession.h>
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 () |
template<typename T> | |
void | safeReceiveWordArray (T *t, const uint32_t size) |
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) |
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.
QSocketSession::QSocketSession | ( | QSocketDevice * | sd | ) |
Basic constructor.
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.
void QSocketSession::ack | ( | const bool | sign = true |
) | [inline] |
Send an acknowledgement byte through the connection. This matches the waitForAck() method.
sign | The sign of the acknowledgement. This is returned from the matching waitForAck() method on the other side of the connection. |
void QSocketSession::close | ( | ) |
Close the current connection.
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).
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.
opposite | This must be true on one side of the handshake and false on the other. It won't work otherwise. |
const bool QSocketSession::isOpen | ( | ) | [inline] |
Determine if the current connection is open.
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.
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.
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. |
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.
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. |
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.
const uint32_t QSocketSession::safeReceiveWord | ( | ) |
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.
void QSocketSession::safeReceiveWordArray | ( | T * | t, | |
const uint32_t | size | |||
) |
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.
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. |
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.
i | The word to be sent down. |
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.
i | The array of words. Must be at least size big. | |
size | The number of values to be sent. |
const bool QSocketSession::sameByteOrder | ( | ) | const [inline] |
Determine if the two hosts share the same word byte-ordering.
void QSocketSession::sendByte | ( | const uchar | c | ) | [inline] |
Sends a byte value down the connection. Matches receiveByte().
c | The value of the byte to be sent. |
void QSocketSession::sendChunk | ( | const uchar * | buffer, | |
const uint | size | |||
) |
Send a number of bytes down the connection as one single entity. Matches receiveChunk().
buffer | An array of bytes to be sent. | |
size | The size of the array. |
void QSocketSession::sendString | ( | const QCString & | s | ) |
Send a string value down the connection.
s | The QCString value to be sent. |
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.
timeOut | Number of milliseconds to wait before giving up. | |
ackType | If non-0, the sign of the send acknowledgement is populated into boolean here. |
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.
ackType | If non-0, the sign of the send acknowledgement is populated into boolean here. |