|
|
The Socket is used as the base for all Internet protocol services under Common C++. A socket is a system resource (or winsock descriptor) that occupies a specific port address (and may be bound to a specific network interface) on the local machine. The socket may also be directly connected to a specific socket on a remote internet host.
This base class is not directly used, but is provided to offer properties common to other Common C++ socket classes, including the socket exception model and the ability to set socket properties such as QoS, "sockopts" properties like Dont-Route and Keep-Alive, etc.
mutable struct | struct |
[protected]
SOCKET so | so |
[protected]
sockstate_t state | state |
[protected]
sockerror_t Error (sockerror_t error, char *errstr = NULL)
| Error |
[protected const]
This service is used to throw all socket errors which usually occur during the socket constructor.
Parameters:
error | defined socket error id. |
errstr | string or message to pass. |
inline void Error (char *estr)
| Error |
[protected]
This service is used to throw application defined socket errors where the application specific error code is a string.
Parameters:
errstr | string or message to pass. |
inline void setError (bool enable)
| setError |
[protected]
This service is used to turn the error handler on or off for "throwing" exceptions by manipulating the thrown flag.
Parameters:
true | to enable handler. |
void endSocket (void)
| endSocket |
[protected]
Used as the default destructor for ending a socket. This will cleanly terminate the socket connection. It is provided for use in derived virtual destructors.
sockerror_t connectError (void)
| connectError |
[protected]
Used as a common handler for connection failure processing.
Returns: correct failure code to apply.
sockerror_t setBroadcast (bool enable)
| setBroadcast |
[protected]
Set the subnet broadcast flag for the socket. This enables sending to a subnet and may require special image privileges depending on the operating system.
Parameters:
enable | when set to true. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t setMulticast (bool enable)
| setMulticast |
[protected]
Setting multicast binds the multicast interface used for the socket to the interface the socket itself has been implicitly bound to. It is also used as a check flag to make sure multicast is enabled before multicast operations are used.
Parameters:
enable | when set to true. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t setLoopback (bool enable)
| setLoopback |
[protected]
Set the multicast loopback flag for the socket. Loopback enables a socket to hear what it is sending.
Parameters:
enable | when set to true. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t setTimeToLive (unsigned char ttl)
| setTimeToLive |
[protected]
Set the multicast time to live for a multicast socket.
Parameters:
time | to live. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t Join (const InetMcastAddress &ia)
| Join |
[protected]
Join a multicast group.
Parameters:
ia | address of multicast group to join. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t Drop (const InetMcastAddress &ia)
| Drop |
[protected]
Drop membership from a multicast group.
Parameters:
address | of multicast group to drop. |
Returns: 0 (SOCKET_SUCCESS) on success, else error code.
sockerror_t setRouting (bool enable)
| setRouting |
[protected]
Set the socket routing to indicate if outgoing messages should bypass normal routing (set false).
Parameters:
enable | normal routing when set to true. |
Returns: 0 on success.
sockerror_t setNoDelay (bool enable)
| setNoDelay |
[protected]
Enable/disable delaying packets (Nagle algorithm)
Parameters:
disable | Nagle algorithm when set to true. |
Returns: 0 on success.
Socket (int domain, int type, int protocol = 0)
| Socket |
[protected]
An unconnected socket may be created directly on the local machine. Sockets can occupy both the internet domain (AF_INET) and UNIX socket domain (AF_UNIX) under unix. The socket type (SOCK_STREAM, SOCK_DGRAM) and protocol may also be specified. If the socket cannot be created, an exception is thrown.
Parameters:
domain | socket domain to use. |
type | base type and protocol family of the socket. |
protocol | specific protocol to apply. |
Socket (SOCKET fd)
| Socket |
[protected]
A socket object may be created from a file descriptor when that descriptor was created either through a socket() or accept() call. This constructor is mostly for internal use.
Parameters:
fd | file descriptor of an already existing socket. |
Socket (const Socket &source)
| Socket |
[protected]
A socket can also be constructed from an already existing Socket object. The socket file descriptor is dup()'d. This does not exist under win32.
Parameters:
source | of existing socket to clone. |
ssize_t Readline (char *buf, size_t len, timeout_t timeout = 0)
| Readline |
[protected]
Process a logical input line from a socket descriptor directly.
Parameters:
pointer | to string. |
maximum | length to read. |
timeout | for pending data in milliseconds. |
Returns: number of bytes actually read.
~Socket ()
| ~Socket |
[virtual]
The socket base class may be "thrown" as a result of an error, and the "catcher" may then choose to destroy the object. By assuring the socket base class is a virtual destructor, we can assure the full object is properly terminated.
Socket & operator= (const Socket &from)
| operator= |
Sockets may also be duplicated by the assignment operator.
InetHostAddress getSender (tpport_t *port = NULL)
| getSender |
[const]
May be used to examine the origin of data waiting in the socket receive queue. This can tell a TCP server where pending "connect" requests are coming from, or a UDP socket where it's next packet arrived from.
Parameters:
ptr | to port number of sender. |
Returns: host address, test with "isInetAddress()".
InetHostAddress getPeer (tpport_t *port = NULL)
| getPeer |
[const]
Get the host address and port of the socket this socket is connected to. If the socket is currently not in a connected state, then a host address of 0.0.0.0 is returned.
Parameters:
ptr | to port number of remote socket. |
Returns: host address of remote socket.
InetHostAddress getLocal (tpport_t *port = NULL)
| getLocal |
[const]
Get the local address and port number this socket is currently bound to.
Parameters:
ptr | to port number on local host. |
Returns: host address of interface this socket is bound to.
void setCompletion (bool immediate)
| setCompletion |
Used to specify blocking mode for the socket. A socket can be made non-blocking by setting setCompletion(false) or set to block on all access with setCompletion(true). I do not believe this form of non-blocking socket I/O is supported in winsock, though it provides an alternate asynchronous set of socket services.
Parameters:
mode | specify socket I/O call blocking mode. |
sockerror_t setLinger (bool linger)
| setLinger |
Enable lingering sockets on close.
Parameters:
specify | linger enable. |
sockerror_t setKeepAlive (bool enable)
| setKeepAlive |
Set the keep-alive status of this socket and if keep-alive messages will be sent.
Parameters:
enable | keep alive messages. |
Returns: 0 on success.
sockerror_t setTypeOfService (socktos_t service)
| setTypeOfService |
Set packet scheduling on platforms which support ip quality of service conventions. This effects how packets in the queue are scheduled through the interface.
Parameters:
type | of service enumerated type. |
Returns: 0 on success, error code on failure.
bool isConnected (void)
| isConnected |
[const]
Can test to see if this socket is "connected", and hence whether a "catch" can safely call getPeer(). Of course, an unconnected socket will return a 0.0.0.0 address from getPeer() as well.
Returns: true when socket is connected to a peer.
bool isActive (void)
| isActive |
[const]
Test to see if the socket is at least operating or if it is mearly initialized. "initialized" sockets may be the result of failed constructors.
Returns: true if not in initial state.
bool operator! ()
| operator! |
[const]
Operator based testing to see if a socket is currently active.
inline bool isBroadcast (void)
| isBroadcast |
[const]
Return if broadcast has been enabled for the specified socket.
Returns: true if broadcast socket.
inline bool isRouted (void)
| isRouted |
[const]
Return if socket routing is enabled.
Returns: true if routing enabled.
inline sockerror_t getErrorNumber (void)
| getErrorNumber |
[const]
Often used by a "catch" to fetch the last error of a thrown socket.
Returns: error number of sockerror_t error.
inline const char * getErrorString (void)
| getErrorString |
[const]
Often used by a "catch" to fetch the user set error string of a thrown socket, but only if EXTENDED error codes are used.
Returns: string for error message.
bool isPending (sockpend_t pend, timeout_t timeout = TIMEOUT_INF)
| isPending |
[virtual]
Get the status of pending operations. This can be used to examine if input or output is waiting, or if an error has occured on the descriptor.
Parameters:
ready | check to perform. |
timeout | in milliseconds, inf. if not specified. |
Returns: true if ready, false on timeout.