socket.h

GNU Common C++ is a very portable and highly optimized class framework for writing C++ applications

	 * @return host address, test with "isInetAddress()".
	 */
	IPV4Host getIPV4Sender(tpport_t *port = NULL) const;

	inline IPV4Host getSender(tpport_t *port = NULL) const
		{return getIPV4Sender(port);}

#ifdef	CCXX_IPV6
	IPV6Host getIPV6Sender(tpport_t *port = NULL) const;
#endif

	/**
	 * 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.
	 *
	 * @param port ptr to port number of remote socket.
	 * @return host address of remote socket.
	 */
	IPV4Host getIPV4Peer(tpport_t *port = NULL) const;

	inline IPV4Host getPeer(tpport_t *port = NULL) const
		{return getIPV4Peer(port);}

#ifdef	CCXX_IPV6
	IPV6Host getIPV6Peer(tpport_t *port = NULL) const;
#endif

	/**
	 * Get the local address and port number this socket is
	 * currently bound to.
	 *
	 * @param port ptr to port number on local host.
	 * @return host address of interface this socket is bound to.
	 */
	IPV4Host getIPV4Local(tpport_t *port = NULL) const;

	inline IPV4Host getLocal(tpport_t *port = NULL) const
		{return getIPV4Local(port);}

#ifdef	CCXX_IPV6
	IPV6Host getIPV6Local(tpport_t *port = NULL) const;
#endif

	/**
	 * Perform NAT table lookup for this socket.
	 * Used to allow an application to know the original ip:port 
	 * pair the the client "thinks" it is connecting to. Used mostly 
	 * to transparently impersonate a remote server/service.
	 *
	 * On error, 0.0.0.0:0 is returned and one of the following error codes 
	 * is set: errServiceUnavailable - if nat is not supported on the 
	 * current platform or if it was not compiled; errLookupFail - if the
	 * nat syscall failed for some reason (extended error code); 
	 * errSearchErr - if the socket does not have nat information (i.e.
	 * is not nated).
	 * 
	 * NAT lookup is supported on NetFilter for ipv4 and ipv6 (Linux), 
	 * IPFilter for ipv4 (Solaris, *BSD except OpenBSD, HP-UX, etc.) and
	 * Packet Filter for ipv4 and ipv6 (OpenBSD).
	 * When using IPFilter or Packet Filter, the first NAT lookup must be 
	 * performed as root (the NAT device is read only for root and is opened
	 * once, unless an error occurs). Permissions on the nat device may be
	 * changed to solve this.
	 *
	 * \warning When using IPFilter and Packet Filter, application data model
	 * must be the same as the running kernel (32/64 bits).
	 *
	 * @param port ptr to NATed port number on local host. 
	 * @return NATed host address that this socket is related to.
	 */
	IPV4Host getIPV4NAT(tpport_t *port = NULL) const;

	inline IPV4Host getNAT(tpport_t *port) const
		{return getIPV4NAT(port);}

#ifdef	CCXX_IPV6
	IPV6Host getIPV6NAT(tpport_t *port = NULL) const;
#endif

	/**
	 * 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.
	 * 
	 * @param immediate mode specify socket I/O call blocking mode.
	 */
	void setCompletion(bool immediate);

	/**
	 * Enable lingering sockets on close.
	 *
	 * @param linger specify linger enable.
	 */
	Error setLinger(bool linger);

	/**
	 * Set the keep-alive status of this socket and if keep-alive
	 * messages will be sent.
	 *
	 * @return 0 on success.
	 * @param enable keep alive messages.
	 */
	Error setKeepAlive(bool enable);

	/**
	 * Set packet scheduling on platforms which support ip quality
	 * of service conventions.  This effects how packets in the
	 * queue are scheduled through the interface.
	 *
	 * @return 0 on success, error code on failure.
	 * @param service type of service enumerated type.
	 */
	Error setTypeOfService(Tos service);

	/**
	 * 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.
	 *
	 * @return true when socket is connected to a peer.
	 */
	bool isConnected(void) 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.
	 *
	 * @return true if not in initial state.
	 */
	bool isActive(void) const;

	/**
	 * Operator based testing to see if a socket is currently
	 * active.
	 */
	bool operator!() const;

	/**
	 * Return if broadcast has been enabled for the specified
	 * socket.
	 *
	 * @return true if broadcast socket.
	 */
	inline bool isBroadcast(void) const
		{return flags.broadcast;};

	/**
	 * Return if socket routing is enabled.
	 *
	 * @return true if routing enabled.
	 */
	inline bool isRouted(void) const
		{return flags.route;};

	/**
 	 * Often used by a "catch" to fetch the last error of a thrown
	 * socket.
	 * 
	 * @return error number of Error error.
 	 */
	inline Error getErrorNumber(void) const {return errid;}
	
	/**
 	 * Often used by a "catch" to fetch the user set error string
	 * of a thrown socket, but only if EXTENDED error codes are used.
	 * 
	 * @return string for error message.
 	 */
	inline const char *getErrorString(void) const {return errstr;}

	inline long getSystemError(void) const {return syserr;}

	const char *getSystemErrorString(void) const;

	/**
	 * 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.
	 *
	 * @return true if ready, false on timeout.
	 * @param pend ready check to perform.
	 * @param timeout in milliseconds, inf. if not specified.
	 */
	virtual bool isPending(Pending pend, timeout_t timeout = TIMEOUT_INF);
};

/**
 * UDP sockets implement the TCP SOCK_DGRAM UDP protocol.  They can be
 * used to pass unverified messages between hosts, or to broadcast a
 * specific message to an entire subnet.  Please note that Streaming of
 * realtime data commonly use UDPDuplex related classes rather than
 * UDPSocket.
 * 
 * In addition to connected TCP sessions, Common C++ supports UDP sockets and
 * these also cover a range of functionality.  Like a TCPSocket, A UDPSocket
 * can be created bound to a specific network interface and/or port address,
 * though this is not required.  UDP sockets also are usually either 
 * connected or otherwise "associated" with a specific "peer" UDP socket.
 * Since UDP sockets operate through discreet packets, there are no streaming
 * operators used with UDP sockets.
 * 
 * In addition to the UDP "socket" class, there is a "UDPBroadcast" class.
 * The UDPBroadcast is a socket that is set to send messages to a subnet as a
 * whole rather than to an individual peer socket that it may be associated
 * with.
 * 
 * UDP sockets are often used for building "realtime" media  streaming
 * protocols and full duplex messaging services.  When used in this manner,
 * typically a pair of UDP sockets are used together; one socket is used to
 * send and the other to receive data with an associated pair of UDP sockets
 * on a "peer" host.  This concept is represented through the Common C++
 * UDPDuplex object, which is a pair of sockets that communicate with another
 * UDPDuplex pair.
 * 
 * 
 * @author David Sugar <[e-mail]>
 * @short Unreliable Datagram Protocol sockets.
 */
class __EXPORT UDPSocket : public Socket
{
private:
	inline Error setKeepAlive(bool enable)
		{return Socket::setKeepAlive(enable);};

protected:
#ifdef	CCXX_IPV6
	union
	{
		struct sockaddr_in6 ipv6;
		struct sockaddr_in ipv4;
	}	peer;
#else
	union
	{
		struct sockaddr_in ipv4;
	}	peer;
#endif

	Family family;

public:
	/**
	 * Create an unbound UDP socket, mostly for internal use.
	 */
	UDPSocket(Family family = IPV4);

	/**
	 * Create a UDP socket bound by a service name.
	 */
	UDPSocket(const char *name, Family family = IPV4);

	/**
	 * Create a UDP socket and bind it to a specific interface
	 * and port address so that other UDP sockets on remote
	 * machines (or the same host) may find and send UDP messages
	 * to it.  On failure to bind, an exception is thrown.
	 * 
	 * @param bind address to bind this socket to.
	 * @param port number to bind this socket to.
	 */
	UDPSocket(const IPV4Address &bind, tpport_t port);
#ifdef	CCXX_IPV6
	UDPSocket(const IPV6Address &bind, tpport_t port);
#endif

	/**
	 * Destroy a UDP socket as a socket.
	 */
	virtual ~UDPSocket();

	/**
	 * Set the loopback.
	 */
	inline Error setLoopback(bool enable)
		{return Socket::setLoopbackByFamily(enable, family);}

	/**
	 * Set the multicast.
	 */
	inline Error setMulticast(bool enable)
		{return Socket::setMulticastByFamily(enable, family);}

	/**
	 * Set time to live.
	 */
	inline Error setTimeToLive(char ttl)
		{return Socket::setTimeToLiveByFamily(ttl, family);}

	/**
	 * set the peer address to send message packets to.  This can be
	 * set before every send() call if nessisary.
	 *
	 * @param host address to send packets to.
	 * @param port number to deliver packets to.
	 */
	void setPeer(const IPV4Host &host, tpport_t port);
	void connect(const IPV4Host &host, tpport_t port);
#ifdef	CCXX_IPV6
	void setPeer(const IPV6Host &host, tpport_t port);
	void connect(const IPV6Host &host, tpport_t port);
#endif

        /**
         * get the interface index for a named network device
         *
         * @param ethX is device name, like "eth0" or "eth1"
         * @param InterfaceIndex is the index value returned by os
	 * @todo Win32 and ipv6 specific implementation.
         */
        Socket::Error getInterfaceIndex(const char *ethX,int& InterfaceIndex);

        /**
         * join a multicast group on a particular interface
         *
         * @param ia is the multicast address to use
         * @param InterfaceIndex is the index value returned by 
	 * getInterfaceIndex
	 * @todo Win32 and ipv6 specific implementation.
         */
        Socket::Error join(const IPV4Multicast &ia,int InterfaceIndex);


	/**
	 * Send a message packet to a peer host.
	 *
	 * @param buf pointer to packet buffer to send.
	 * @param len of packet buffer to send.
	 * @return number of bytes sent.
	 */
	ssize_t send(const void *buf, size_t len);

	/**
	 * Receive a message from any host.
	 *
	 * @param buf pointer to packet buffer to receive.
	 * @param len of packet buffer to receive.
	 * @param reply save sender address for reply if true.
	 * @return number of bytes received.
	 */
	ssize_t receive(void *buf, size_t len, bool reply = false);

	/**
	 * Examine address of sender of next waiting packet.  This also
	 * sets "peer" address to the sender so that the next "send"
	 * message acts as a "reply".  This additional behavior overides
	 * the standard socket getSender behavior.
	 *
	 * @param port pointer to hold port number.
	 */
	IPV4Host getIPV4Peer(tpport_t *port = NULL) const;
	inline IPV4Host getPeer(tpport_t *port = NULL) const
		{return getIPV4Peer(port);}

#ifdef	CCXX_IPV6
	IPV6Host getIPV6Peer(tpport_t *port = NULL) const;
#endif

	/**
	 * Examine contents of next waiting packet.
	 *
	 * @param buf pointer to packet buffer for contents.
	 * @param len of packet buffer.
	 * @return number of bytes examined.
	 */
	inline ssize_t peek(void *buf, size_t len)
		{return _IORET64 ::recv(so, (char *)buf, _IOLEN64 len, MSG_PEEK);};

	/**
	 * Associate socket with a named connection
	 */
	void setPeer(const char *service);
	void connect(const char *service);

	/**
         * Disassociate this socket from any host connection.  No data
         * should be read or written until a connection is established.
         */
        Error disconnect(void);
};


/**
 * Representing a UDP socket used for subnet broadcasts, this class
 * provides an alternate binding and setPeer() capability for UDP
 * sockets.
 *
 * @author David Sugar <[e-mail]>
 * @short Unreliable Datagram for subnet broadcasts.
 */
class __EXPORT UDPBroadcast : public UDPSocket
{
private:
	void setPeer(const IPV4Host &ia, tpport_t port);

	Error setBroadcast(bool enable)
		{return Socket::setBroadcast(enable);};

public:
	/**
	 * Create and bind a subnet broadcast socket.
	 *
	 * @param ia address to bind socket under locally.
	 * @param port to bind socket under locally.
	 */
	UDPBroadcast(const IPV4Address &ia, tpport_t port);

	/**
	 * Set peer by subnet rather than specific host.
	 *
	 * @param subnet of peer hosts to send to.
	 * @param port number to use.
	 */
	void setPeer(const IPV4Broadcast &subnet, tpport_t port);
};	

/**
 * Representing half of a two-way UDP connection, the UDP transmitter
 * can broadcast data to another selected peer host or to an entire
 * subnet.
 *
 * @author David Sugar <[e-mail]>
 * @short Unreliable Datagram Peer Associations.
 */
class __EXPORT UDPTransmit : protected UDPSocket
{
private:
	/**
	 * Common code for diferent flavours of Connect (host, broadcast,
	 * multicast).
	 *
	 * @param ia network address to associate with
	 * @param port port number to associate with
	 */
	Error cConnect(const IPV4Address &ia, tpport_t port);

protected:
	/**
	 * Create a UDP transmitter.
	 */
	UDPTransmit(Family family = IPV4);

	/**
	 * Create a UDP transmitter, bind it to a specific interface
	 * and port address so that other UDP sockets on remote
	 * machines (or the same host) may find and send UDP messages
	 * to it, and associate it with a given port on a peer host.  
         * On failure to bind, an exception is thrown.  This class is
	 * only used to build the UDP Duplex.
	 * 
	 * @param bind address to bind this socket to.
	 * @param port number to bind this socket to.
	 */
	UDPTransmit(const IPV4Address &bind, tpport_t port = 5005);
#ifdef	CCXX_IPV6
	UDPTransmit(const IPV6Address &bind, tpport_t port = 5005);
#endif

	/**
	 * Associate this socket with a specified peer host.  The port
	 * number from the constructor will be used.  All UDP packets
	 * will be sent to and received from the specified host.
	 *
	 * @return 0 on success, -1 on error.
	 * @param host address to connect socket to.
	 * @param port to connect socket to.
	 */
	Error connect(const IPV4Host &host, tpport_t port);
#ifdef	CCXX_IPV6
	Error connect(const IPV6Address &host, tpport_t port);
#endif

	/**
	 * Associate this socket with a subnet of peer hosts for
	 * subnet broadcasting.  The server must be able to assert
	 * broadcast permission for the socket.
	 *
	 * @return 0 on success, -1 on error.
	 * @param subnet subnet address to broadcast into.
	 * @param port transport port to broadcast into.