1

#ifndef NETWORK_SOCKET_HH

     2

#define NETWORK_SOCKET_HH

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Network sockets

     8

 */

     9

    10

// forward-declare

    11

class NetworkSocket;

    12

    13

#include "../Error.hh"

    14

#include "Platform.hh"

    15

#include "Address.hh"

    16

#include "Reactor.hh"

    17

    18

/**

    19

 * This is a socket class that wraps an OS socket filedescriptor and provides the more important socket operations

    20

 * as methods. The implementation aims to be address-family agnostic, and should thence work with both IPv6 and IPv4.

    21

 *

    22

 * Network addresses are abstracted into the NetworkEndpoint and derived NetworkAddress classes. The bind() and

    23

 * connect() methods accept a NetworkEndpoint as an argument, which allows them to handle hosts with multiple

    24

 * addresses (such as all dual-stack IPv6/IPv4 hosts). Other methods such as accept(), recv() and send() require a

    25

 * NetworkAddress, which encodes a single specific address. Note how these are also useable as arguments to

    26

 * connect()/bind().

    27

 *

    28

 * The constructor accepts family/socktype/protocol arguments (as passed to the socket() syscall) which can be used to

    29

 * limit which kinds of addresses/sockets will be used. Usually, family can be specified as AF_UNSPEC and socktype as

    30

 * either SOCK_STREAM or SOCK_DGRAM - this will let bind()/connect() pick the best IPv6/IPv4 address for use.

    31

 *

    32

 * Note however that a call to bind()/connect() can result to multiple calls to the socket() syscall - this interaction

    33

 * is slightly complicated. On a succesfull bind() operation, the resulting socket will be "locked down", meaning that

    34

 * a later connect() operation will use the same local socket - this restricts the remote address families that are valid.

    35

 *

    36

 * The behaviour of send/recv differs from the behaviour of the similarly named syscalls. On failure,

    37

 * NetworkSocketErrno is thrown, and on EOF, NetworkSocketEOFError. Zero is returned if the syscall returns EAGAIN - in

    38

 * other words - if a socket is nonblocking and the operation would block. Otherwise, the return value is the same as

    39

 * for the syscalls - the number of bytes send/received.

    40

 *

    41

 * NetworkSockets also support polling for non-blocking operations using NetworkReactor. A socket is associated with a

    42

 * specific reactor (passed to the constructor, defaults to NetworkReactor::current). This is inherited by accept()'d

    43

 * sockets. For read/write, NetworkSocket provides a sig_read()/sig_write() signal which will be fired if a socket is

    44

 * registered using set_poll_read(true)/set_poll_write(true) and the NetworkReactor::poll is run. The internal logic

    45

 * does not manipulate the poll states. Usually, sig_read will always be enabled (except to throttle incoming traffic),

    46

 * and sig_write should be enabled after send() returns zero (XXX: provide an automatic mechanism for this?).

    47

 */

    48

class NetworkSocket {

    49

    private:

    50

        /**

    51

         * Socket family/type/protocol

    52

         */

    53

        struct socket_type {

    54

            /** Socket domain */

    55

            int family;

    56

    57

            /** Socket type */

    58

            int socktype;

    59

    60

            /** Socket protocol */

    61

            int protocol;

    62

    63

            /** Simple constructor */

    64

            socket_type (int family = 0, int socktype = 0, int protocol = 0) : family(family), socktype(socktype), protocol(protocol) { }

    65

        };

    66

    67

        /** These are nonzero if given via the constructor, used to filter out unwanted addrinfos */

    68

        socket_type sock_type;

    69

    70

        /** The file descriptor */

    71

        int fd;

    72

    73

        /** Our current type as used for fd, intialized via constructor, but updated by lazy_socket */

    74

        socket_type type;

    75

    76

        /** 

    77

         * Has the socket been explicitly bind()'d? If so, force ourselves to use this socket in connect().

    78

         */

    79

        bool bound : 1;

    80

    81

        /**

    82

         * Registered to reactor?

    83

         */

    84

        bool registered : 1;

    85

    86

        /**

    87

         * Do we want to know about recv()s?

    88

         */

    89

        bool want_read : 1;

    90

    91

        /**

    92

         * Is the write buffer full?

    93

         */

    94

        bool want_write : 1;

    95

    96

        /**

    97

         * The reactor that we use, defaults to NetworkReactor::current

    98

         */

    99

        NetworkReactor *reactor;

   100

   101

        /**

   102

         * Read/write signals

   103

         */

   104

        CL_Signal_v0 _sig_read, _sig_write;

   105

   106

    public:

   107

        /**

   108

         * Construct a socket of the specific type. Family and protocol can be left as NULL, but type should usually

   109

         * be specified. The given reactor is used for polling, defaults to NetworkReactor::current

   110

         */

   111

        NetworkSocket (int family, int socktype, int protocol = 0, NetworkReactor *reactor = NULL);

   112

   113

        /**

   114

         * Create a socket from the given pre-existing fd

   115

         */

   116

        NetworkSocket (int fd, socket_type type, NetworkReactor *reactor = NULL);

   117

   118

        /**

   119

         * Force-close the socket if it's still open

   120

         */

   121

        ~NetworkSocket (void);

   122

   123

    private:

   124

        // nocopy

   125

        NetworkSocket (const NetworkSocket &copy);

   126

        NetworkSocket &operator= (const NetworkSocket &copy);

   127

   128

        /**

   129

         * Reset bound+poll

   130

         */ 

   131

        void reset (void);

   132

   133

        /**

   134

         * Create a new socket of the given type, unless we already have one

   135

         */

   136

        void lazy_socket (int family, int type, int protocol);

   137

   138

        /**

   139

         * Close and reset, ignoring errors

   140

         */

   141

        void force_close (void);

   142

   143

    public:

   144

        /**

   145

         * Get the socket fd... promise not to break it

   146

         */

   147

        int get_socket (void) const { return fd; }

   148

   149

        /**

   151

         */ 

   152

        void bind (const NetworkEndpoint &addr);

   153

   154

        /**

   156

         */

   157

        void listen (int backlog);

   158

   159

        /**

   160

         * Get local address

   163

         */

   164

        NetworkAddress get_local_address (void); 

   165

   166

        /**

   167

         * Get remote address

   170

         */

   171

        NetworkAddress get_remote_address (void); 

   172

   173

        /**

   176

         */

   177

        void set_nonblocking (bool nonblocking);

   178

   179

        /**

   184

         */

   185

        NetworkSocket* accept (NetworkAddress *src);

   186

   187

        /**

   191

         */

   192

        void connect (const NetworkEndpoint &addr);

   193

   194

        /**

   195

         * Send, optionally using the specific destination

   196

         *

   197

         * @param buf bytes to send

   198

         * @param size how many bytes to try and send

   199

         * @param dest optional specific destination address

   200

         * @return number of bytes sent, zero if busy

   201

         * @throw NetworkSocketError on error

   202

         */

   203

        size_t send (const char *buf, size_t size, const NetworkAddress *dest = NULL);

   204

   205

        /**

   206

         * Recv, optionally storing the source in src

   207

         *

   208

         * @param buf where to recv into

   209

         * @param size how many bytes to try and receive

   210

         * @param src optionally store source address

   211

         * @return number of bytes received, zero if none available

   212

         * @throw NetworkSocketEOFError if the connection was closed

   213

         * @throw NetworkSocketError on error

   214

         */

   215

        size_t recv (char *buf, size_t size, NetworkAddress *src = NULL);

   216

   217

        /**

   218

         * Close and reset the socket

   219

         */

   220

        void close (void);

   221

   222

        /**

   223

         * Triggered when socket becomes readable

   224

         */

   225

        CL_Signal_v0& sig_read (void) { return _sig_read; }

   226

   227

        /**

   228

         * Triggered when socket becomes writeable after a send that returned zero

   229

         */

   230

        CL_Signal_v0& sig_write (void) { return _sig_write; }

   231

   232

        /**

   233

         * Register to NetworkReactor unless already registered

   234

         */

   235

        void register_poll (void);

   236

   237

        /**

   239

         */

   240

        void set_poll_read (bool want_read) { this->want_read = want_read; if (!registered) register_poll(); }

   241

   242

        /**

   244

         */

   245

        void set_poll_write (bool want_write) { this->want_write = want_write; if (!registered) register_poll(); }

   246

   247

        /**

   249

         */

   250

        NetworkPollMask get_poll (void) { 

   251

            return (want_read ? POLL_READ : 0) | (want_write ? POLL_WRITE : 0); 

   252

        }

   253

   254

        /**

   256

         */

   257

        void notify (NetworkPollMask mask) { 

   258

            if (mask & POLL_READ) _sig_read();

   259

            if (mask & POLL_WRITE) _sig_write();

   260

        }

   261

};

   262

   263

/**

   264

 * Base class for expcetions thrown by socket methods

   265

 */

   266

class NetworkSocketError : public Error {

   267

    protected:

   268

        static std::string build_str (const NetworkSocket &socket, const char *op, const char *err);

   269

   270

    public:

   271

        NetworkSocketError (const NetworkSocket &socket, const char *op, const char *err);

   272

};

   273

   274

/**

   275

 * Errno-enabled exception, most common type of NetworkSocketError

   276

 */

   277

class NetworkSocketErrno : public NetworkSocketError {

   278

    public:

   279

        NetworkSocketErrno (const NetworkSocket &socket, const char *op);

   280

};

   281

   282

/**

   283

 * Recv returned EOF

   284

 */

   285

class NetworkSocketEOFError : public NetworkSocketError {

   286

    public:

   287

        NetworkSocketEOFError (const NetworkSocket &socket, const char *op) :

   288

            NetworkSocketError(socket, op, "EOF") { }

   289

};

   290

   291

#endif /* NETWORK_SOCKET_HH */