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

    20

/**

    21

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

    22

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

    23

 *

    24

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

    25

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

    26

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

    27

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

    28

 * connect()/bind().

    29

 *

    30

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

    31

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

    32

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

    33

 *

    34

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

    35

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

    36

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

    37

 *

    38

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

    39

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

    40

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

    41

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

    42

 *

    43

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

    44

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

    45

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

    46

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

    47

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

    48

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

    49

 */

    50

class NetworkSocket {

    51

    private:

    52

        /**

    53

         * Socket family/type/protocol

    54

         */

    55

        struct socket_type {

    56

            /** Socket domain */

    57

            int family;

    58

    59

            /** Socket type */

    60

            int socktype;

    61

    62

            /** Socket protocol */

    63

            int protocol;

    64

    65

            /** Simple constructor */

    66

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

    67

        };

    68

    69

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

    70

        socket_type sock_type;

    71

    72

        /** The file descriptor */

    73

        int fd;

    74

    75

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

    76

        socket_type type;

    77

    78

        /** 

    79

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

    80

         */

    81

        bool bound : 1;

    82

    83

        /**

    84

         * Registered to reactor?

    85

         */

    86

        bool registered : 1;

    87

    88

        /**

    89

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

    90

         */

    91

        bool want_read : 1;

    92

    93

        /**

    94

         * Is the write buffer full?

    95

         */

    96

        bool want_write : 1;

    97

    98

        /**

    99

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

   100

         */

   101

        NetworkReactor *reactor;

   102

   103

        /**

   104

         * Read/write signals

   105

         */

   106

        CL_Signal_v0 _sig_read, _sig_write;

   107

   108

    public:

   109

        /**

   110

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

   111

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

   112

         */

   113

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

   114

   115

        /**

   116

         * Create a socket from the given pre-existing fd

   117

         */

   118

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

   119

   120

        /**

   121

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

   122

         */

   123

        ~NetworkSocket (void);

   124

   125

    private:

   126

        // nocopy

   127

        NetworkSocket (const NetworkSocket &copy);

   128

        NetworkSocket &operator= (const NetworkSocket &copy);

   129

   130

        /**

   131

         * Reset bound+poll

   132

         */ 

   133

        void reset (void);

   134

   135

        /**

   136

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

   137

         */

   138

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

   139

   140

        /**

   141

         * Close and reset, ignoring errors

   142

         */

   143

        void force_close (void);

   144

   145

    public:

   146

        /**

   147

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

   148

         */

   149

        int get_socket (void) const { return fd; }

   150

   151

        /**

   152

         * Bind to a local endpoint. This can be specified in hostname form, and a suitable socket will be chosen.

   153

         */ 

   154

        void bind (const NetworkEndpoint &addr);

   155

   156

        /**

   157

         * Put socket into listen mode for accept()

   158

         */

   159

        void listen (int backlog);

   160

   161

        /**

   162

         * Get local address

   163

         *

   164

         * Note that this may block on a reverse DNS lookup.

   165

         */

   166

        NetworkAddress get_local_address (void); 

   167

   168

        /**

   169

         * Get remote address

   170

         *

   171

         * Note that this may block on a reverse DNS lookup.

   172

         */

   173

        NetworkAddress get_remote_address (void); 

   174

   175

        /**

   176

         * Make send/recv non-blocking. The current connect() implementation does not support use of non-blocking

   177

         * connects.

   178

         */

   179

        void set_nonblocking (bool nonblocking);

   180

   181

        /**

   182

         * Accept an incoming connection on a listen() socket as a new socket, optionally storing the connection's

   183

         * source address.

   184

         *

   185

         * Note that this may block on a reverse DNS lookup if \a src is given.

   186

         */

   187

        NetworkSocket* accept (NetworkAddress *src);

   188

   189

        /**

   190

         * Connect this socket to a remote endpoint, going through the resolved addresses until we find one that works.

   191

         *

   192

         * This is currently implemented in an entirely blocking fashion, DNS lookups and connect() included.

   193

         */

   194

        void connect (const NetworkEndpoint &addr);

   195

   196

        /**

   197

         * Send, optionally using the specific destination

   198

         *

   199

         * @param buf bytes to send

   200

         * @param size how many bytes to try and send

   201

         * @param dest optional specific destination address

   202

         * @return number of bytes sent, zero if busy

   203

         * @throw NetworkSocketError on error

   204

         */

   205

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

   206

   207

        /**

   208

         * Recv, optionally storing the source in src

   209

         *

   210

         * @param buf where to recv into

   211

         * @param size how many bytes to try and receive

   212

         * @param src optionally store source address

   213

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

   214

         * @throw NetworkSocketEOFError if the connection was closed

   215

         * @throw NetworkSocketError on error

   216

         */

   217

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

   218

   219

        /**

   220

         * Close and reset the socket

   221

         */

   222

        void close (void);

   223

   224

        /**

   225

         * Triggered when socket becomes readable

   226

         */

   227

        CL_Signal_v0& sig_read (void) { return _sig_read; }

   228

   229

        /**

   230

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

   231

         */

   232

        CL_Signal_v0& sig_write (void) { return _sig_write; }

   233

   234

        /**

   235

         * Register to NetworkReactor unless already registered

   236

         */

   237

        void register_poll (void);

   238

   239

        /**

   240

         * Trigger sig_read() once socket is ready for recv()

   241

         */

   242

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

   243

   244

        /**

   245

         * Trigger sig_write() once socket is ready for send()

   246

         */

   247

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

   248

   249

        /**

   250

         * What events this socket is interested in (called by NetworkReactor)

   251

         */

   252

        NetworkPollMask get_poll (void) { 

   253

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

   254

        }

   255

   256

        /**

   257

         * Notify of events (called by NetworkReactor)

   258

         */

   259

        void notify (NetworkPollMask mask) { 

   260

            if (mask & POLL_READ) _sig_read();

   261

            if (mask & POLL_WRITE) _sig_write();

   262

        }

   263

};

   264

   265

/**

   266

 * Base class for expcetions thrown by socket methods

   267

 */

   268

class NetworkSocketError : public Error {

   269

    protected:

   270

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

   271

   272

    public:

   273

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

   274

};

   275

   276

/**

   277

 * Errno-enabled exception, most common type of NetworkSocketError

   278

 */

   279

class NetworkSocketErrno : public NetworkSocketError {

   280

    public:

   281

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

   282

};

   283

   284

/**

   285

 * Recv returned EOF

   286

 */

   287

class NetworkSocketEOFError : public NetworkSocketError {

   288

    public:

   289

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

   290

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

   291

};

   292

   293

#endif /* NETWORK_SOCKET_HH */