dlib C++ Library - sockets_kernel_abstract.h

// Copyright (C) 2003 Davis E. King (davis@dlib.net)
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_SOCKETS_KERNEl_ABSTRACT_
#ifdef DLIB_SOCKETS_KERNEl_ABSTRACT_
#include <string>
#include "../threads.h"
namespace dlib
{
// ----------------------------------------------------------------------------------------
 /*!
 GENERAL COMMENTS:
 Nothing in here will throw exceptions. 
 
 All ip address strings in this file refer to IPv4 addresses. For 
 example "192.168.1.1"
 Timeouts:
 All timeout values are measured in milliseconds but you are not 
 guaranteed to have that level of resolution. The actual resolution
 is implementation defined.
 GENERAL WARNING
 Don't call any of these functions or make any of these objects 
 before main() has been entered. 
 EXCEPTIONS
 Unless specified otherwise, nothing in this file throws exceptions.
 !*/
// ----------------------------------------------------------------------------------------
 // LOOKUP FUNCTIONS
 // all lookup functions are thread-safe
 int get_local_hostname (
 std::string& hostname
 );
 /*!
 ensures
 - if (#get_local_hostname() == 0) then
 - #hostname == a string containing the hostname of the local computer 
 - returns 0 upon success
 - returns OTHER_ERROR upon failure and in this case #hostname's value 
 is undefined
 !*/ 
// -----------------
 int hostname_to_ip (
 const std::string& hostname,
 std::string& ip,
 int n = 0
 );
 /*!
 requires
 - n >= 0
 ensures
 - if (#hostname_to_ip() == 0) then
 - #ip == string containing the nth ip address associated with the hostname
 - returns 0 upon success 
 - returns OTHER_ERROR upon failure 
 !*/
// -----------------
 int ip_to_hostname (
 const std::string& ip,
 std::string& hostname
 );
 /*!
 ensures
 - if (#ip_to_hostname() == 0) then
 - #hostname == string containing the hostname associated with ip
 - returns 0 upon success 
 - returns OTHER_ERROR upon failure 
 !*/
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
 //
 // socket creation functions
 // 
 // The following functions are guaranteed to be thread-safe
 //
// ----------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------- 
 int create_listener (
 listener*& new_listener,
 unsigned short port,
 const std::string& ip = ""
 );
 /*!
 requires
 - 0 <= port <= 65535
 ensures
 - if (#create_listener() == 0) then
 - #new_listener == a pointer to a listener object that is listening on 
 the specified port and ip for an incoming connection 
 - if (ip == "") then 
 - the new listener will be listening on all interfaces 
 - if (port == 0) then 
 - the operating system will assign a free port to listen on 
 - returns 0 if create_listener was successful 
 - returns PORTINUSE if the specified local port was already in use 
 - returns OTHER_ERROR if some other error occurred
 !*/
 int create_listener (
 std::unique_ptr<listener>& new_listener,
 unsigned short port,
 const std::string& ip = ""
 );
 /*!
 This function is just an overload of the above function but it gives you a
 std::unique_ptr smart pointer instead of a C pointer.
 !*/
 int create_connection ( 
 connection*& new_connection,
 unsigned short foreign_port, 
 const std::string& foreign_ip, 
 unsigned short local_port = 0,
 const std::string& local_ip = ""
 );
 /*!
 requires
 - 0 < foreign_port <= 65535 
 - 0 <= local_port <= 65535
 ensures
 - if (#create_connection() == 0) then
 - #new_connection == a pointer to a connection object that is connected 
 to foreign_ip on port foreign_port and is using the local interface 
 local_ip and local port local_port
 - #new_connection->user_data == 0
 - if (local_ip == "") then 
 - the operating system will chose this for you
 - if (local_port == 0) then 
 - the operating system will chose this for you
 - returns 0 if create_connection was successful 
 - returns PORTINUSE if the specified local port was already in use 
 - returns OTHER_ERROR if some other error occurred
 !*/
 int create_connection ( 
 std::unique_ptr<connection>& new_connection,
 unsigned short foreign_port, 
 const std::string& foreign_ip, 
 unsigned short local_port = 0,
 const std::string& local_ip = ""
 );
 /*!
 This function is just an overload of the above function but it gives you a
 std::unique_ptr smart pointer instead of a C pointer.
 !*/
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
 // connection object
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
 class connection
 {
 /*!
 WHAT THIS OBJECT REPRESENTS
 This object represents a TCP connection.
 Instances of this class can only be created by using the 
 create_connection function or listener class defined below.
 NOTE: 
 A connection object must ALWAYS be closed (delete the pointer to the 
 connection) or it will cause a resource leak. 
 Note also that all errors indicated by a return code of OTHER_ERROR
 are fatal so if one occurs the connection should just be closed.
 CLOSING A CONNECTION
 Note that if ~connection() or shutdown() is called before the remote client 
 has received all sent data it is possible that the data will be lost. To 
 avoid this you should call the close_gracefully() function to close your 
 connections (unless you actually do want to immediately dispose of a 
 connection and don't care about the data).
 (example: close_gracefully(con); // close con gracefully but force it closed
 // if it takes more than 500 milliseconds.)
 THREAD SAFETY
 - It is always safe to call shutdown() or shutdown_outgoing(). 
 - you may NOT call any function more than once at a time (except the 
 shutdown functions).
 - do not call read() more than once at a time
 - do not call write() more than once at a time
 - You can safely call shutdown or shutdown_outgoing in conjunction with 
 the read/write functions.
 This is helpful if you want to unblock another thread that is 
 blocking on a read/write operation. Shutting down the connection 
 will cause the read/write functions to return a value of SHUTDOWN.
 OUT-OF-BAND DATA:
 All out-of-band data will be put inline into the normal data stream.
 This means that you can read any out-of-band data via calls to read(). 
 (i.e. the SO_OOBINLINE socket option will be set) 
 !*/
 public:
 ~connection (
 );
 /*!
 requires
 - no other threads are using this connection object 
 ensures
 - closes the connection (this is an abrupt non-graceful close) 
 - frees the resources used by this object
 !*/
 void* user_data;
 /*!
 This pointer is provided so that the client programmer may easily associate
 some data with a connection object. You can really do whatever you want
 with it. Initially user_data is 0.
 !*/
 long write (
 const char* buf, 
 long num
 );
 /*!
 requires
 - num > 0 
 - buf points to an array of at least num bytes
 ensures
 - will block until ONE of the following occurs:
 - num bytes from buf have been written to the connection 
 - an error has occurred
 - the outgoing channel of the connection has been shutdown locally
 - returns num if write succeeded 
 - returns OTHER_ERROR if there was an error (this could be due to a 
 connection close)
 - returns SHUTDOWN if the outgoing channel of the connection has been 
 shutdown locally
 !*/
 long read (
 char* buf, 
 long num
 );
 /*!
 requires
 - num > 0 
 - buf points to an array of at least num bytes
 ensures
 - read() will not read more than num bytes of data into #buf 
 - read blocks until ONE of the following happens:
 - there is some data available and it has been written into #buf 
 - the remote end of the connection is closed 
 - an error has occurred
 - the connection has been shutdown locally
 - returns the number of bytes read into #buf if there was any data.
 - returns 0 if the connection has ended/terminated and there is no more data.
 - returns OTHER_ERROR if there was an error.
 - returns SHUTDOWN if the connection has been shutdown locally
 !*/
 long read (
 char* buf, 
 long num,
 unsigned long timeout 
 );
 /*!
 requires
 - num > 0 
 - buf points to an array of at least num bytes
 - timeout < 2000000 
 ensures
 - read() will not read more than num bytes of data into #buf 
 - if (timeout > 0) then read() blocks until ONE of the following happens:
 - there is some data available and it has been written into #buf 
 - the remote end of the connection is closed 
 - an error has occurred
 - the connection has been shutdown locally
 - timeout milliseconds has elapsed
 - else
 - read() does not block
 - returns the number of bytes read into #buf if there was any data.
 - returns 0 if the connection has ended/terminated and there is no more data.
 - returns TIMEOUT if timeout milliseconds elapsed before we got any data.
 - returns OTHER_ERROR if there was an error.
 - returns SHUTDOWN if the connection has been shutdown locally
 !*/
 unsigned short get_local_port (
 ) const;
 /*!
 ensures
 - returns the local port number for this connection
 !*/
 unsigned short get_foreign_port ( 
 ) const;
 /*!
 ensures
 - returns the foreign port number for this connection
 !*/
 const std::string& get_local_ip (
 ) const;
 /*!
 ensures
 - returns the IP of the local interface this connection is using
 !*/
 const std::string& get_foreign_ip (
 ) const;
 /*!
 ensures
 - returns the IP of the foreign host for this connection
 !*/
 int shutdown (
 );
 /*!
 ensures
 - if (#shutdown() == 0 && connection was still open) then
 - terminates the connection but does not free the resources for the 
 connection object 
 - any read() or write() calls on this connection will return immediately 
 with the code SHUTDOWN.
 - returns 0 upon success 
 - returns OTHER_ERROR if there was an error
 !*/ 
 int shutdown_outgoing (
 );
 /*!
 ensures
 - if (#shutdown_outgoing() == 0 && outgoing channel was still open) then
 - sends a FIN to indicate that no more data will be sent on this 
 connection but leaves the receive half of the connection open to 
 receive more data from the other host 
 - any calls to write() will return immediately with the code SHUTDOWN.
 - returns 0 upon success 
 - returns OTHER_ERROR if there was an error 
 !*/
 int disable_nagle(
 );
 /*!
 ensures
 - Sets the TCP_NODELAY socket option to disable Nagle's algorithm.
 This can sometimes reduce transmission latency, however, in almost
 all normal cases you don't want to mess with this as the default
 setting is usually appropriate. 
 - returns 0 upon success
 - returns OTHER_ERROR if there was an error 
 !*/
 typedef platform_specific_type socket_descriptor_type;
 socket_descriptor_type get_socket_descriptor (
 ) const;
 /*!
 ensures
 - returns the underlying socket descriptor for this connection
 object. The reason you might want access to this is to 
 pass it to some other library that requires a socket file 
 descriptor. However, if you do this then you probably shouldn't 
 use the dlib::connection read() and write() anymore since
 whatever you are doing with the socket descriptor is probably 
 doing I/O with the socket.
 !*/
 private:
 // restricted functions
 connection();
 connection(connection&); // copy constructor
 connection& operator=(connection&); // assignment operator
 }; 
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
 // listener object
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
 class listener
 {
 /*!
 WHAT THIS OBJECT REPRESENTS
 This object represents a TCP socket waiting for incoming connections.
 Calling accept returns a pointer to any new incoming connections on its
 port.
 Instances of this class can only be created by using the 
 create_listener function defined below.
 NOTE: 
 A listener object must ALWAYS be closed (delete the pointer to it) or 
 it will cause a resource leak. 
 Note also that all errors indicated by a return code of OTHER_ERROR
 are fatal so if one occurs the listener should be closed.
 THREAD SAFETY
 None of the functions in this object are guaranteed to be thread-safe.
 This means that you must serialize all access to this object.
 !*/
 public:
 ~listener (
 );
 /*!
 requires
 - no other threads are using this listener object 
 ensures
 - closes the listener 
 - frees the resources used by this object
 !*/
 int accept (
 connection*& new_connection,
 unsigned long timeout = 0
 );
 /*!
 requires
 - timeout < 2000000 
 ensures
 - blocks until a new connection is ready or timeout milliseconds have 
 elapsed.
 - #new_connection == a pointer to the new connection object 
 - #new_connection->user_data == 0
 - if (timeout == 0) then 
 - the timeout argument is ignored
 - returns 0 if accept() was successful 
 - returns TIMEOUT if timeout milliseconds have elapsed 
 - returns OTHER_ERROR if an error has occurred 
 !*/
 int accept (
 std::unique_ptr<connection>& new_connection,
 unsigned long timeout = 0
 );
 /*!
 This function is just an overload of the above function but it gives you a
 std::unique_ptr smart pointer instead of a C pointer.
 !*/
 unsigned short get_listening_port (
 ) const;
 /*!
 ensures
 - returns the port number that this object is listening on
 !*/
 const std::string& get_listening_ip (
 ) const;
 /*!
 ensures
 - returns a string containing the IP (e.g. "127.0.0.1") of the 
 interface this object is listening on 
 - returns "" if it is accepting connections on all interfaces
 !*/
 private:
 // restricted functions
 listener();
 listener(listener&); // copy constructor
 listener& operator=(listener&); // assignment operator
 };
}
#endif // DLIB_SOCKETS_KERNEl_ABSTRACT_