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_