Class DClient



Each DClient manages a single TCP connection. It sends and receives data, and can connect to servers. DClient takes a DEngine in its constructor, which dispatches the DClient's events. Details on event handling can be found in the Event Handling section. See the SimpleClient sample program for an example.

Boost::ASIO may schedule events on a socket for a short while after it has been closed. To safely delete a socket, disconnect it and wait for a call to DEngine::update to complete. This will clear any pending events from the sockets queue. To delete a socket immediately, use DEngine::deleteSocket.

Constructors

Networking

Event Handlers


DClient(DEngine *engine)

The default constructor, used when the DClient will be connecting to a server. engine is a pointer to the DEngine that will provide our events.


DClient(DEngine *engine, unsigned int bufferSize)

Same as above, but allows us to set the size of the DClient's send and receive buffers to bufferSize bytes. Larger buffer sizes can result in better efficiency. The default size is 16 kilobytes, which is already quite large for most networks.


DClient(DEngine *engine, boost::asio::ip::tcp::socket *newSocket)

This constructor should be used in DServer's connectHandler function. newSocket is a connection that was accepted by the DServer, and will be used by the created DClient.


DClient(DEngine *engine, boost::asio::ip::tcp::socket *newSocket, unsigned int bufferSize)

Same as above, but allows us to set the size of the DClient's send and receive buffers to bufferSize bytes. Larger buffer sizes can result in better efficiency. The default size is 16 kilobytes, which is already quite large for most networks.


bool closeSocket(void)

Closes the DClient's socket. Returns false on errors and sets errMsg. closeSocket is automatically called by the destructor.


unsigned int getBufferSize(void)

Returns the size of the send and receive buffers in bytes.


string getErrMsg(void)

Returns a description of the most recent error.


string getLocalAddress(void)

Returns this DClient's local address. Returns an empty string if an error occurred, and sets errMsg with a description of the problem.


string getRemoteAddress(void)

Returns the address of the host this DClient is connected to. Returns an empty string if an error occurred, and sets errMsg with a description of the problem.


bool isConnected(void)

Returns true if this DClient is currently connected, false otherwise.


virtual void send(const DBuffer &theData)

Sends theData to the remote host. sendHandler is called when all data is sent.


bool setDelay(bool enabled)

Enables or disables Nagle's algorithm. By default, Nagle's algorithm is active. If many small pieces of data are sent in a short time period, they're bundled together and sent in the same TCP packet. This improves efficiency, as each TCP packet has an overhead of 40 bytes or more. However, Nagle's algorithm increases latency as the data isn't sent immediately, as it's buffered in case it can be combined with another message.

If enabled is false, then Nagle's Algorithm will be disabled, and the send function will send the data immediately. setDelay returns false if it couldn't change the socket settings, and sets errMsg.


void startConnect(const string &hostName, uint16_t portNumber, IpVersion ipVersion, boost::function<void (std::string, NetworkCode)> connectHandler)

Causes the DClient to connect to the server at the specified hostName, which can be an IP address or domain name. portNumber is the TCP port the server is listening on. ipVersion should be set to either DA_IPV4 or DA_IPV6.

connectHandler will be called when the connection either fails or completes. It has the following method signature: void connectHandler(string errorDesc, NetworkCode status) The NetworkCode is an enumeration that will be set to one of the following values: 

    DA_SUCCESS =         0, the connection succeeded
    DA_HOSTNAME_ERROR = -1, couldn't resolve the host name
    DA_CLOSE_ERROR =    -2, the socket was already open and we couldn't close it
    DA_CONNECT_ERROR =  -3, couldn't connect to the specified host

The string is an error description that will be set if the connection attempt failed.


virtual unsigned long int unsentBytes(void)

Returns the number of bytes remaining to be sent.


void setErrorHandler(boost::function<void (string, bool)> errorHandler)

Set the event handler that's called in response to a socket error. The string contains a description of the problem. If the bool is false, the connection is no longer valid and the socket should be closed. Otherwise, it should be possible to recover from the error.


void setReceiveHandler(boost::function<void (libdasyne::DBuffer&)> recvHandler)

Set the event handler that's called when data is received from the network. The DBuffer contains the data.


void setSendHandler(boost::function<void (void)> sendHandler)

Set the event handler that's called when the DClient has sent all pending data.





















Back to class reference