Branch data Line data Source code
1 : : // Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC")
2 : : //
3 : : // Permission to use, copy, modify, and/or distribute this software for any
4 : : // purpose with or without fee is hereby granted, provided that the above
5 : : // copyright notice and this permission notice appear in all copies.
6 : : //
7 : : // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8 : : // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 : : // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
10 : : // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 : : // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 : : // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 : : // PERFORMANCE OF THIS SOFTWARE.
14 : :
15 : : #ifndef __IO_SOCKET_H
16 : : #define __IO_SOCKET_H 1
17 : :
18 : : // IMPORTANT NOTE: only very few ASIO headers files can be included in
19 : : // this file. In particular, asio.hpp should never be included here.
20 : : // See the description of the namespace below.
21 : : #include <unistd.h> // for some network system calls
22 : :
23 : : #include <functional>
24 : : #include <string>
25 : :
26 : : #include <exceptions/exceptions.h>
27 : :
28 : : namespace isc {
29 : : namespace asiolink {
30 : :
31 : : /// \brief The \c IOSocket class is an abstract base class to represent
32 : : /// various types of network sockets.
33 : : ///
34 : : /// This class is a wrapper for the ASIO socket classes such as
35 : : /// \c ip::tcp::socket and \c ip::udp::socket.
36 : : ///
37 : : /// Derived class implementations are completely hidden within the
38 : : /// implementation. User applications only get access to concrete
39 : : /// \c IOSocket objects via the abstract interfaces.
40 : : ///
41 : : /// We may revisit this decision when we generalize the wrapper and more
42 : : /// modules use it. Also, at that point we may define a separate (visible)
43 : : /// derived class for testing purposes rather than providing factory methods
44 : : /// (i.e., getDummy variants below).
45 : : class IOSocket {
46 : : ///
47 : : /// \name Constructors and Destructor
48 : : ///
49 : : /// Note: The copy constructor and the assignment operator are
50 : : /// intentionally defined as private, making this class non-copyable.
51 : : //@{
52 : : private:
53 : : IOSocket(const IOSocket& source);
54 : : IOSocket& operator=(const IOSocket& source);
55 : : protected:
56 : : /// \brief The default constructor.
57 : : ///
58 : : /// This is intentionally defined as \c protected as this base class
59 : : /// should never be instantiated (except as part of a derived class).
60 : 119 : IOSocket() {}
61 : : public:
62 : : /// The destructor.
63 : 119 : virtual ~IOSocket() {}
64 : : //@}
65 : :
66 : : /// \brief Return the "native" representation of the socket.
67 : : ///
68 : : /// In practice, this is the file descriptor of the socket for
69 : : /// UNIX-like systems so the current implementation simply uses
70 : : /// \c int as the type of the return value.
71 : : /// We may have to need revisit this decision later.
72 : : ///
73 : : /// In general, the application should avoid using this method;
74 : : /// it essentially discloses an implementation specific "handle" that
75 : : /// can change the internal state of the socket (consider the
76 : : /// application closes it, for example).
77 : : /// But we sometimes need to perform very low-level operations that
78 : : /// requires the native representation. Passing the file descriptor
79 : : /// to a different process is one example.
80 : : /// This method is provided as a necessary evil for such limited purposes.
81 : : ///
82 : : /// This method never throws an exception.
83 : : ///
84 : : /// \return The native representation of the socket. This is the socket
85 : : /// file descriptor for UNIX-like systems.
86 : : virtual int getNative() const = 0;
87 : :
88 : : /// \brief Return the transport protocol of the socket.
89 : : ///
90 : : /// Currently, it returns \c IPPROTO_UDP for UDP sockets, and
91 : : /// \c IPPROTO_TCP for TCP sockets.
92 : : ///
93 : : /// This method never throws an exception.
94 : : ///
95 : : /// \return IPPROTO_UDP for UDP sockets
96 : : /// \return IPPROTO_TCP for TCP sockets
97 : : virtual int getProtocol() const = 0;
98 : :
99 : : /// \brief Return a non-usable "dummy" UDP socket for testing.
100 : : ///
101 : : /// This is a class method that returns a "mock" of UDP socket.
102 : : /// This is not associated with any actual socket, and its only
103 : : /// responsibility is to return \c IPPROTO_UDP from \c getProtocol().
104 : : /// The only feasible usage of this socket is for testing so that
105 : : /// the test code can prepare some "UDP data" even without opening any
106 : : /// actual socket.
107 : : ///
108 : : /// This method never throws an exception.
109 : : ///
110 : : /// \return A reference to an \c IOSocket object whose \c getProtocol()
111 : : /// returns \c IPPROTO_UDP.
112 : : static IOSocket& getDummyUDPSocket();
113 : :
114 : : /// \brief Return a non-usable "dummy" TCP socket for testing.
115 : : ///
116 : : /// See \c getDummyUDPSocket(). This method is its TCP version.
117 : : ///
118 : : /// \return A reference to an \c IOSocket object whose \c getProtocol()
119 : : /// returns \c IPPROTO_TCP.
120 : : static IOSocket& getDummyTCPSocket();
121 : : };
122 : :
123 : : } // namespace asiolink
124 : : } // namespace isc
125 : :
126 : : #endif // __IO_SOCKET_H
|
