Represents a low-level network socket. More...

#include <Socket.h>

Inheritance diagram for kNet::Socket:

Collaboration diagram for kNet::Socket:

Public Member Functions
void	SetSendBufferSize (int bytes)
	Sets the underlying socket send buffer (SO_SNDBUF) size.
void	SetReceiveBufferSize (int bytes)
	Sets the underlying socket receive buffer (SO_RCVBUF) size.
int	SendBufferSize () const
	Returns the current value for the send buffer of this socket.
int	ReceiveBufferSize () const
	Returns the current value for the receive buffer of this socket.
bool	Connected () const
	Returns true if the connection is both write-open AND read-open.
bool	IsReadOpen () const
	Returns true if the connection is open for reading from.
bool	IsWriteOpen () const
	Returns true if the connection is open for writing to.
void	MarkReadClosed ()
	Forces this socket to be treated as if it has been read-closed.
void	MarkWriteClosed ()
	Forces this socket to be treated as if it has been write-closed.
bool	IsUDPServerSocket () const
	If this function returns true, this socket represents a UDP server socket instance.
bool	IsUDPSlaveSocket () const
	Returns whether this socket is a UDP slave socket. [worker thread].
void	Disconnect ()
	Performs a write close operation on the socket, signalling the other end that no more data will be sent.
void	Close ()
	Performs an immediate write and read close on the socket, without waiting for the connection to gracefully shut down.
bool	Send (const char *data, size_t numBytes)
	Sends the given data through the socket.
OverlappedTransferBuffer *	BeginSend ()
	Starts the sending of new data.
bool	EndSend (OverlappedTransferBuffer *send)
	Finishes and queues up the given transfer that was created with a call to BeginSend.
void	AbortSend (OverlappedTransferBuffer *send)
	Cancels the sending of data.
bool	IsOverlappedSendReady ()
	Returns true if it is possible to send out new data. In this case, a call to BeginSend will succeed.
Event	GetOverlappedSendEvent ()
	Returns the event object that should be waited on to receive a notification when it is possible to send out new data.
size_t	Receive (char dst, size_t maxBytes, EndPoint endPoint=0)
	Waits for the max given amount of time for new data to be received from the socket.
OverlappedTransferBuffer *	BeginReceive ()
	Call to receive new data from the socket.
void	EndReceive (OverlappedTransferBuffer *buffer)
	Finishes a read operation on the socket. Frees the given buffer to be re-queued for a future socket read operation.
bool	IsOverlappedReceiveReady () const
	Returns true if there is new data to be read in. In that case, BeginReceive() will not return 0.
Event	GetOverlappedReceiveEvent ()
	Returns the event object that will be notified whenever data is available to be read from the socket.
SocketTransportLayer	TransportLayer () const
	Returns which transport layer the connection is using. This value is either SocketOverUDP or SocketOverTCP.
SocketType	Type () const
	Returns the type of this socket object.
size_t	MaxSendSize () const
	Returns the maximum amount of bytes that can be sent through to the network in one call.
const EndPoint &	LocalEndPoint () const
	Returns the local EndPoint this socket is bound to.
const char *	LocalAddress () const
	Returns the local address (local hostname) of the local end point this socket is bound to.
unsigned short	LocalPort () const
	Returns the local port that this socket is bound to.
const EndPoint &	RemoteEndPoint () const
	Returns the remote EndPoint this socket is connected to.
const char *	DestinationAddress () const
	Returns the destination address (destination hostname) of the remote end point this socket is connected to.
unsigned short	DestinationPort () const
	Returns the destination port of the remote end point this socket is connected to.
std::string	ToString () const
	Returns a human-readable representation of this socket, specifying the peer address and port this socket is connected to.
void	SetBlocking (bool isBlocking)
	Sets the socket to blocking or nonblocking state.
void	SetNaglesAlgorithmEnabled (bool enabled)
	Enables or disables the use of Nagle's algorithm (TCP_NODELAY) for this socket.

Detailed Description

Represents a low-level network socket.

Member Function Documentation

bool kNet::Socket::IsReadOpen ( ) const [inline]

Returns true if the connection is open for reading from.

This does not mean that there necessarily is new data to be immediately read - it only means that the socket is open for receiving data.

References IsOverlappedReceiveReady().

Referenced by kNet::MessageConnection::Close(), kNet::MessageConnection::Disconnect(), kNet::MessageConnection::DumpStatus(), kNet::MessageConnection::GetConnectionState(), kNet::MessageConnection::IsReadOpen(), and kNet::MessageConnection::UpdateConnection().

bool kNet::Socket::IsUDPServerSocket ( ) const [inline]

If this function returns true, this socket represents a UDP server socket instance.

For a UDP server, the data for all clients is received through this same socket, and there are no individual sockets created for each new connection, like is done with TCP.

Referenced by BeginReceive(), EndSend(), Receive(), and ToString().

void kNet::Socket::Disconnect ( )

Performs a write close operation on the socket, signalling the other end that no more data will be sent.

Any data currently left in the send buffers will be sent over to the other side, but no new data can be sent. The connection will remain half-open for reading, and Receive() calls may still be made to the socket. When a read returns 0, the connection will be transitioned to bidirectionally closed state (Connected() will return false).

References kNet::Network::GetErrorString(), kNet::Network::GetLastError(), LOG, and ToString().

bool kNet::Socket::Send	(	const char *	data,
		size_t	numBytes
	)

Sends the given data through the socket.

This function may only be called if Socket::IsWriteOpen() returns true. If the socket is not write-open, calls to this function will fail. This function is an orthogonal API to the overlapped IO Send routines. Do not mix these API calls when doing networking, but instead choose one preferred method and consistently use it.

Returns:: True on success, false otherwise.

Todo:

References Close(), kNet::Network::GetErrorString(), kNet::Network::GetLastError(), LOG, kNet::ServerListenSocket, SetBlocking(), and ToString().

OverlappedTransferBuffer * kNet::Socket::BeginSend ( )

Starts the sending of new data.

After having filled the data to send to the OverlappedTransferBuffer that is returned here, commit the send by calling EndSend. If you have called BeginSend, but decide not to send any data, call AbortSend instead (otherwise memory will leak).

Returns:: A transfer buffer where the data to send is to be filled in. If no new data can be sent at this time, this function returns 0.

Todo:: In debug mode - track this pointer.

References kNet::Network::GetErrorString(), kNet::Network::GetLastError(), and LOG.

bool kNet::Socket::EndSend ( OverlappedTransferBuffer * send )

Finishes and queues up the given transfer that was created with a call to BeginSend.

Returns:: True if send succeeded, false otherwise. In either case, the ownership of the passed buffer send is taken by this Socket and may not be accessed anymore. Discard the pointer after calling this function.

References kNet::Network::GetErrorString(), kNet::Network::GetLastError(), IsUDPServerSocket(), LOG, and ToString().

void kNet::Socket::AbortSend ( OverlappedTransferBuffer * send )

Cancels the sending of data.

Call this function if you first call BeginSend, but decide you don't want to send the data. This frees the given buffer, do not dereference it after calling this function.

References LOG.

size_t kNet::Socket::Receive	(	char *	dst,
		size_t	maxBytes,
		EndPoint *	endPoint = `0`
	)

Waits for the max given amount of time for new data to be received from the socket.

Returns:: True if new data was received, false if the timeout period elapsed. Reads in data from the socket. If there is no data available, this function will not block, but will immediately return 0. This function issues an immediate recv() call to the socket and is not compatible with the Overlapped Transfer API above. Do not mix the use of these two APIs, but pick one method to use and stay with it.

Parameters:

endPoint

[out] If the socket is an UDP socket that is not bound to an address, this will contain the source address.

Returns:: The number of bytes that were successfully read.

Todo:: Mark UDP server and client sockets separately. For a server socket, we cannot Close() here, but for client sockets it is safe.

References Close(), kNet::EndPoint::FromSockAddrIn(), kNet::Network::GetErrorString(), kNet::Network::GetLastError(), IsUDPServerSocket(), IsUDPSlaveSocket(), LOG, and ToString().

Referenced by BeginReceive().

OverlappedTransferBuffer * kNet::Socket::BeginReceive ( )

Call to receive new data from the socket.

Returns:: A buffer that contains the data, or 0 if no new data was available. When you are finished reading the buffer, call EndReceive to free up the buffer, or memory will leak.

References kNet::Network::GetErrorString(), kNet::Network::GetLastError(), IsUDPServerSocket(), IsUDPSlaveSocket(), LOG, Receive(), kNet::EndPoint::ToSockAddrIn(), and ToString().

Referenced by kNet::NetworkServer::ReadUDPSocketData().

size_t kNet::Socket::MaxSendSize ( ) const [inline]

Returns the maximum amount of bytes that can be sent through to the network in one call.

If you try sending more data than specified by this value, the result is undefined.

Referenced by kNet::MessageConnection::EndAndQueueMessage().

const EndPoint& kNet::Socket::RemoteEndPoint ( ) const [inline]

Returns the remote EndPoint this socket is connected to.

If SocketType == ServerListenSocket, this socket is not bound to any remote end point, and so the returned struct is uninitialized (filled with zeroes).

Referenced by kNet::MessageConnection::RemoteEndPoint().

const char* kNet::Socket::DestinationAddress ( ) const [inline]

Returns the destination address (destination hostname) of the remote end point this socket is connected to.

If SocketType == ServerListenSocket, returns an empty string.

Referenced by ToString().

unsigned short kNet::Socket::DestinationPort ( ) const [inline]

Returns the destination port of the remote end point this socket is connected to.

If SocketType == ServerListenSocket, returns 0.

Referenced by ToString().

std::string kNet::Socket::ToString ( ) const

Returns a human-readable representation of this socket, specifying the peer address and port this socket is connected to.

References Connected(), DestinationAddress(), DestinationPort(), kNet::EndPoint::FromSockAddrIn(), IsUDPServerSocket(), IsUDPSlaveSocket(), and kNet::EndPoint::ToString().

Referenced by BeginReceive(), Close(), Disconnect(), EndSend(), kNet::MessageConnection::HandleInboundMessage(), kNet::NetworkServer::Process(), kNet::NetworkServer::ReadUDPSocketData(), Receive(), Send(), kNet::Network::StartServer(), and kNet::MessageConnection::ToString().

void kNet::Socket::SetNaglesAlgorithmEnabled ( bool enabled )

Enables or disables the use of Nagle's algorithm (TCP_NODELAY) for this socket.

Nagle's algorithm reduces the bandwidth consumption of the channel, but can increase latency. Conversely, disabling Nagle's algorithm improves the latency, but increases the number of IP packets sent to the network. By default, Nagle's algorithm is enabled. Read more about Nagle's algorithm here: http://msdn.microsoft.com/en-us/library/ms817942.aspx

References kNet::Network::GetLastErrorString(), and LOG.

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

C:/knet/include/kNet/Socket.h
C:/knet/src/Socket.cpp

kNet::Socket Class Reference

Public Member Functions

Detailed Description

Member Function Documentation