terom@382: #ifndef NETWORK_ENDPOINT_HH
terom@382: #define NETWORK_ENDPOINT_HH
terom@185: 
terom@399: /**
terom@399:  * @file
terom@399:  *
terom@399:  * Textual NetworkEndpoint addresses
terom@378:  */
terom@399: 
terom@399: #include "../Error.hh"
terom@399: #include "Platform.hh"
terom@378: 
terom@378: #include <string>
terom@378: 
terom@378: // assume...
terom@378: #if INET6_ADDRSTRLEN < INET_ADDRSTRLEN
terom@378:     #error INET6_ADDRSTRLEN is smaller than INET_ADDRSTRLEN
terom@378: #endif
terom@378: 
terom@378: /**
terom@399:  * Length of a network address in text form
terom@378:  */
terom@378: const socklen_t NETWORK_ADDRESS_LENGTH = INET6_ADDRSTRLEN;
terom@185: 
terom@284: /**
terom@399:  * NetworkEndpoint is mostly used to pass addresses from the (human) user to NetworkSocket's bind()/connect(). The 
terom@399:  * constructor accepts a textual service name (port) and hostname (literal IP adddress or hostname), and can then
terom@399:  * provide a list of resolved addresses for use by NetworkSocket (using the libc getaddrinfo). Additionally,
terom@399:  * methods/operators are defined for textual output of the address.
terom@399:  *
terom@399:  * It may be of value to note that the hostname/service is only interpreted by the get_addrinfo() method, which means
terom@399:  * that invalid/non-existant hostnames/services will only raise an error once the NetworkEndpoint is passed to
terom@399:  * NetworkSocket.
terom@284:  */ 
terom@381: class NetworkEndpoint {
terom@381:     protected:
terom@378:         /**
terom@378:          * Our human-readable hostname
terom@378:          */
terom@378:         std::string hostname;
terom@378: 
terom@378:         /**
terom@378:          * Our human-readable service
terom@378:          */
terom@378:         std::string service;
terom@378: 
terom@378:     public:
terom@378:         /**
terom@381:          * Construct an empty NetworkEndpoint
terom@378:          */
terom@381:         NetworkEndpoint (void);
terom@378: 
terom@378:         /**
terom@381:          * Construct a NetworkEndpoint with a NULL hostname, and a specific service
terom@378:          */
terom@381:         explicit NetworkEndpoint (std::string service);
terom@378: 
terom@378:         /**
terom@381:          * Construct a NetworkEndpoint on a specific hostname and service
terom@378:          */
terom@381:         NetworkEndpoint (std::string hostname, std::string service);
terom@378:         
terom@380:         /*
terom@380:          * We can use the default copy-constructor and assignment operator
terom@380:          */
terom@378:    
terom@378:     public:    
terom@378:         /**
terom@378:          * Get a addrinfo* for this address using the given family/type/protocol/flags.
terom@378:          *
terom@378:          * Remember to free the returned pointer using freeaddrinfo() after use.
terom@378:          *
terom@378:          * @param family the socket family for hints.ai_family
terom@378:          * @param socktype the socket type for hints.ai_socktype
terom@378:          * @param protoocl the socket protocol for hints.ai_protocol
terom@378:          * @param flags the flags for hints.ai_flags
terom@378:          * @return linked list of addrinfo's
terom@378:          * @throw NetworkAddressError if resolving this address fails
terom@378:          */
terom@381:         virtual addrinfo* get_addrinfo (int family, int socktype, int protocol = 0, int flags = 0) const;
terom@381:         
terom@378:         /**
terom@381:          * Free an addrinfo returned by get_addrinfo
terom@378:          */
terom@381:         virtual void free_addrinfo (addrinfo *info) const;
terom@378: 
terom@378:         /**
terom@378:          * Get the human-readable hostname
terom@378:          */
terom@381:         virtual std::string get_hostname (void) const { return hostname; }
terom@378: 
terom@378:         /**
terom@378:          * Get the human-readable service name
terom@378:          */
terom@381:         virtual std::string get_service (void) const { return service; }
terom@378: };
terom@185: 
terom@284: /**
terom@284:  * Formatted as  [<addr>:<port>]
terom@284:  */
terom@381: std::ostream& operator<< (std::ostream &s, const NetworkEndpoint &addr);
terom@185: 
terom@378: /**
terom@399:  * Errors raised by NetworkEndpoint, so e.g. DNS errors (hostname not found etc.)
terom@378:  */
terom@378: class NetworkAddressError : public Error {
terom@378:     protected:
terom@381:         static std::string build_str (const NetworkEndpoint &addr, const char *op, const char *msg);
terom@378: 
terom@378:     public:
terom@381:         NetworkAddressError (const NetworkEndpoint &addr, const char *op, const char *msg);
terom@378: };
terom@378: 
terom@185: #endif /* NETWORK_ADDRESS_HH */