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_ENDPOINT_H
16 : : #define __IO_ENDPOINT_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 <sys/socket.h> // for sockaddr
24 : :
25 : : #include <functional>
26 : : #include <string>
27 : :
28 : : #include <exceptions/exceptions.h>
29 : : #include <asiolink/io_address.h>
30 : :
31 : : namespace isc {
32 : : namespace asiolink {
33 : :
34 : : /// \brief The \c IOEndpoint class is an abstract base class to represent
35 : : /// a communication endpoint.
36 : : ///
37 : : /// This class is a wrapper for the ASIO endpoint classes such as
38 : : /// \c ip::tcp::endpoint and \c ip::udp::endpoint.
39 : : ///
40 : : /// Derived class implementations are completely hidden within the
41 : : /// implementation. User applications only get access to concrete
42 : : /// \c IOEndpoint objects via the abstract interfaces.
43 : : class IOEndpoint {
44 : : ///
45 : : /// \name Constructors and Destructor
46 : : ///
47 : : /// Note: The copy constructor and the assignment operator are
48 : : /// intentionally defined as private, making this class non-copyable.
49 : : //@{
50 : : private:
51 : : IOEndpoint(const IOEndpoint& source);
52 : : IOEndpoint& operator=(const IOEndpoint& source);
53 : : protected:
54 : : /// \brief The default constructor.
55 : : ///
56 : : /// This is intentionally defined as \c protected as this base class
57 : : /// should never be instantiated (except as part of a derived class).
58 : 404 : IOEndpoint() {}
59 : : public:
60 : : /// The destructor.
61 : 352 : virtual ~IOEndpoint() {}
62 : : //@}
63 : :
64 : : /// \brief Returns the address of the endpoint.
65 : : ///
66 : : /// This method returns an IOAddress object corresponding to \c this
67 : : /// endpoint.
68 : : ///
69 : : /// Note that the return value is a real object, not a reference or
70 : : /// a pointer.
71 : : ///
72 : : /// This is aligned with the interface of the ASIO counterpart:
73 : : /// the \c address() method of \c ip::xxx::endpoint classes returns
74 : : /// an \c ip::address object.
75 : : ///
76 : : /// This also means handling the address of an endpoint using this method
77 : : /// can be expensive. If the address information is necessary in a
78 : : /// performance sensitive context and there's a more efficient interface
79 : : /// for that purpose, it's probably better to avoid using this method.
80 : : ///
81 : : /// This method never throws an exception.
82 : : ///
83 : : /// \return A copy of \c IOAddress object corresponding to the endpoint.
84 : : virtual IOAddress getAddress() const = 0;
85 : :
86 : : /// \brief Returns the port of the endpoint.
87 : : virtual uint16_t getPort() const = 0;
88 : :
89 : : /// \brief Returns the protocol number of the endpoint (TCP, UDP...)
90 : : virtual short getProtocol() const = 0;
91 : :
92 : : /// \brief Returns the address family of the endpoint.
93 : : virtual short getFamily() const = 0;
94 : :
95 : : /// \brief Returns the address of the endpoint in the form of sockaddr
96 : : /// structure.
97 : : ///
98 : : /// The actual instance referenced by the returned value of this method
99 : : /// is of per address family structure: For IPv4 (AF_INET), it's
100 : : /// \c sockaddr_in; for IPv6 (AF_INET6), it's \c sockaddr_in6.
101 : : /// The corresponding port and address members of the underlying structure
102 : : /// will be set in the network byte order.
103 : : ///
104 : : /// This method is "redundant" in that all information to construct the
105 : : /// \c sockaddr is available via the other "get" methods.
106 : : /// It is still defined for performance sensitive applications that need
107 : : /// to get the address information, such as for address based access
108 : : /// control at a high throughput. Internally it is implemented with
109 : : /// minimum overhead such as data copy (this is another reason why this
110 : : /// method returns a reference).
111 : : ///
112 : : /// As a tradeoff, this method is more fragile; it assumes that the
113 : : /// underlying ASIO implementation stores the address information in
114 : : /// the form of \c sockaddr and it can be accessed in an efficient way.
115 : : /// This is the case as of this writing, but if the underlying
116 : : /// implementation changes this method may become much slower or its
117 : : /// interface may have to be changed, too.
118 : : ///
119 : : /// It is therefore discouraged for normal applications to use this
120 : : /// method. Unless the application is very performance sensitive, it
121 : : /// should use the other "get" method to retrieve specific information
122 : : /// of the endpoint.
123 : : ///
124 : : /// The returned reference is only valid while the corresponding
125 : : /// \c IOEndpoint is valid. Once it's destructed the reference will
126 : : /// become invalid.
127 : : ///
128 : : /// \exception None
129 : : /// \return Reference to a \c sockaddr structure corresponding to the
130 : : /// endpoint.
131 : : virtual const struct sockaddr& getSockAddr() const = 0;
132 : :
133 : : bool operator==(const IOEndpoint& other) const;
134 : : bool operator!=(const IOEndpoint& other) const;
135 : :
136 : : /// \brief A polymorphic factory of endpoint from address and port.
137 : : ///
138 : : /// This method creates a new instance of (a derived class of)
139 : : /// \c IOEndpoint object that identifies the pair of given address
140 : : /// and port.
141 : : /// The appropriate derived class is chosen based on the specified
142 : : /// transport protocol. If the \c protocol doesn't specify a protocol
143 : : /// supported in this implementation, an exception of class \c IOError
144 : : /// will be thrown.
145 : : ///
146 : : /// Memory for the created object will be dynamically allocated. It's
147 : : /// the caller's responsibility to \c delete it later.
148 : : /// If resource allocation for the new object fails, a corresponding
149 : : /// standard exception will be thrown.
150 : : ///
151 : : /// \param protocol The transport protocol used for the endpoint.
152 : : /// Currently, only \c IPPROTO_UDP and \c IPPROTO_TCP can be specified.
153 : : /// \param address The (IP) address of the endpoint.
154 : : /// \param port The transport port number of the endpoint
155 : : /// \return A pointer to a newly created \c IOEndpoint object.
156 : : static const IOEndpoint* create(const int protocol,
157 : : const IOAddress& address,
158 : : const unsigned short port);
159 : : };
160 : :
161 : : } // namespace asiolink
162 : : } // namespace isc
163 : : #endif // __IO_ENDPOINT_H
164 : :
165 : : // Local Variables:
166 : : // mode: c++
167 : : // End:
|
