WebSocket++  0.8.0-dev
C++ websocket client/server library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
endpoint.hpp
1 /*
2  * Copyright (c) 2014, Peter Thorson. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  * * Redistributions of source code must retain the above copyright
7  * notice, this list of conditions and the following disclaimer.
8  * * Redistributions in binary form must reproduce the above copyright
9  * notice, this list of conditions and the following disclaimer in the
10  * documentation and/or other materials provided with the distribution.
11  * * Neither the name of the WebSocket++ Project nor the
12  * names of its contributors may be used to endorse or promote products
13  * derived from this software without specific prior written permission.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED. IN NO EVENT SHALL PETER THORSON BE LIABLE FOR ANY
19  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  *
26  */
27 
28 #ifndef WEBSOCKETPP_TRANSPORT_IOSTREAM_HPP
29 #define WEBSOCKETPP_TRANSPORT_IOSTREAM_HPP
30 
31 #include <websocketpp/transport/base/endpoint.hpp>
32 #include <websocketpp/transport/iostream/connection.hpp>
33 
34 #include <websocketpp/uri.hpp>
35 #include <websocketpp/logger/levels.hpp>
36 
37 #include <websocketpp/common/memory.hpp>
38 
39 #include <ostream>
40 
41 namespace websocketpp {
42 namespace transport {
43 namespace iostream {
44 
45 template <typename config>
46 class endpoint {
47 public:
48  /// Type of this endpoint transport component
49  typedef endpoint type;
50  /// Type of a pointer to this endpoint transport component
51  typedef lib::shared_ptr<type> ptr;
52 
53  /// Type of this endpoint's concurrency policy
54  typedef typename config::concurrency_type concurrency_type;
55  /// Type of this endpoint's error logging policy
56  typedef typename config::elog_type elog_type;
57  /// Type of this endpoint's access logging policy
58  typedef typename config::alog_type alog_type;
59 
60  /// Type of this endpoint transport component's associated connection
61  /// transport component.
62  typedef iostream::connection<config> transport_con_type;
63  /// Type of a shared pointer to this endpoint transport component's
64  /// associated connection transport component
65  typedef typename transport_con_type::ptr transport_con_ptr;
66 
67  // generate and manage our own io_service
68  explicit endpoint() : m_output_stream(NULL), m_is_secure(false)
69  {
70  //std::cout << "transport::iostream::endpoint constructor" << std::endl;
71  }
72 
73  /// Register a default output stream
74  /**
75  * The specified output stream will be assigned to future connections as the
76  * default output stream.
77  *
78  * @param o The ostream to use as the default output stream.
79  */
80  void register_ostream(std::ostream * o) {
81  m_alog->write(log::alevel::devel,"register_ostream");
82  m_output_stream = o;
83  }
84 
85  /// Set whether or not endpoint can create secure connections
86  /**
87  * The iostream transport does not provide any security features. As such
88  * it defaults to returning false when `is_secure` is called. However, the
89  * iostream transport may be used to wrap an external socket API that may
90  * provide secure transport. This method allows that external API to flag
91  * whether or not it can create secure connections so that users of the
92  * WebSocket++ API will get more accurate information.
93  *
94  * Setting this value only indicates whether or not the endpoint is capable
95  * of producing and managing secure connections. Connections produced by
96  * this endpoint must also be individually flagged as secure if they are.
97  *
98  * @since 0.3.0-alpha4
99  *
100  * @param value Whether or not the endpoint can create secure connections.
101  */
102  void set_secure(bool value) {
103  m_is_secure = value;
104  }
105 
106  /// Tests whether or not the underlying transport is secure
107  /**
108  * iostream transport will return false by default because it has no
109  * information about the ultimate remote endpoint. This may or may not be
110  * accurate depending on the real source of bytes being input. `set_secure`
111  * may be used by a wrapper API to correct the return value in the case that
112  * secure connections are in fact possible.
113  *
114  * @return Whether or not the underlying transport is secure
115  */
116  bool is_secure() const {
117  return m_is_secure;
118  }
119 
120  /// Sets the write handler
121  /**
122  * The write handler is called when the iostream transport receives data
123  * that needs to be written to the appropriate output location. This handler
124  * can be used in place of registering an ostream for output.
125  *
126  * The signature of the handler is
127  * `lib::error_code (connection_hdl, char const *, size_t)` The
128  * code returned will be reported and logged by the core library.
129  *
130  * @since 0.5.0
131  *
132  * @param h The handler to call on connection shutdown.
133  */
134  void set_write_handler(write_handler h) {
135  m_write_handler = h;
136  }
137 
138  /// Sets the shutdown handler
139  /**
140  * The shutdown handler is called when the iostream transport receives a
141  * notification from the core library that it is finished with all read and
142  * write operations and that the underlying transport can be cleaned up.
143  *
144  * If you are using iostream transport with another socket library, this is
145  * a good time to close/shutdown the socket for this connection.
146  *
147  * The signature of the handler is lib::error_code (connection_hdl). The
148  * code returned will be reported and logged by the core library.
149  *
150  * @since 0.5.0
151  *
152  * @param h The handler to call on connection shutdown.
153  */
154  void set_shutdown_handler(shutdown_handler h) {
155  m_shutdown_handler = h;
156  }
157 protected:
158  /// Initialize logging
159  /**
160  * The loggers are located in the main endpoint class. As such, the
161  * transport doesn't have direct access to them. This method is called
162  * by the endpoint constructor to allow shared logging from the transport
163  * component. These are raw pointers to member variables of the endpoint.
164  * In particular, they cannot be used in the transport constructor as they
165  * haven't been constructed yet, and cannot be used in the transport
166  * destructor as they will have been destroyed by then.
167  *
168  * @param a A pointer to the access logger to use.
169  * @param e A pointer to the error logger to use.
170  */
171  void init_logging(lib::shared_ptr<alog_type> a, lib::shared_ptr<elog_type> e) {
172  m_elog = e;
173  m_alog = a;
174  }
175 
176  /// Initiate a new connection
177  /**
178  * @param tcon A pointer to the transport connection component of the
179  * connection to connect.
180  * @param u A URI pointer to the URI to connect to.
181  * @param cb The function to call back with the results when complete.
182  */
183  void async_connect(transport_con_ptr, uri_ptr, connect_handler cb) {
184  cb(lib::error_code());
185  }
186 
187  /// Initialize a connection
188  /**
189  * Init is called by an endpoint once for each newly created connection.
190  * It's purpose is to give the transport policy the chance to perform any
191  * transport specific initialization that couldn't be done via the default
192  * constructor.
193  *
194  * @param tcon A pointer to the transport portion of the connection.
195  * @return A status code indicating the success or failure of the operation
196  */
198  tcon->register_ostream(m_output_stream);
199  if (m_shutdown_handler) {
200  tcon->set_shutdown_handler(m_shutdown_handler);
201  }
202  if (m_write_handler) {
203  tcon->set_write_handler(m_write_handler);
204  }
205  return lib::error_code();
206  }
207 private:
208  std::ostream * m_output_stream;
209  shutdown_handler m_shutdown_handler;
210  write_handler m_write_handler;
211 
212  lib::shared_ptr<elog_type> m_elog;
213  lib::shared_ptr<alog_type> m_alog;
214  bool m_is_secure;
215 };
216 
217 
218 } // namespace iostream
219 } // namespace transport
220 } // namespace websocketpp
221 
222 #endif // WEBSOCKETPP_TRANSPORT_IOSTREAM_HPP
void set_shutdown_handler(shutdown_handler h)
Sets the shutdown handler.
Definition: endpoint.hpp:154
config::alog_type alog_type
Type of this endpoint's access logging policy.
Definition: endpoint.hpp:58
void register_ostream(std::ostream *o)
Register a default output stream.
Definition: endpoint.hpp:80
void init_logging(lib::shared_ptr< alog_type > a, lib::shared_ptr< elog_type > e)
Initialize logging.
Definition: endpoint.hpp:171
config::concurrency_type concurrency_type
Type of this endpoint's concurrency policy.
Definition: endpoint.hpp:54
endpoint type
Type of this endpoint transport component.
Definition: endpoint.hpp:49
void async_connect(transport_con_ptr, uri_ptr, connect_handler cb)
Initiate a new connection.
Definition: endpoint.hpp:183
lib::function< lib::error_code(connection_hdl)> shutdown_handler
Definition: base.hpp:61
bool is_secure() const
Tests whether or not the underlying transport is secure.
Definition: endpoint.hpp:116
void set_secure(bool value)
Set whether or not endpoint can create secure connections.
Definition: endpoint.hpp:102
void handle_accept(connection_ptr con, lib::error_code const &ec)
Handler callback for start_accept.
lib::error_code init(transport_con_ptr tcon)
Initialize a connection.
Definition: endpoint.hpp:197
void set_write_handler(write_handler h)
Sets the write handler.
Definition: endpoint.hpp:134
lib::function< void(lib::error_code const &)> connect_handler
The type and signature of the callback passed to the connect method.
Definition: endpoint.hpp:72
config::elog_type elog_type
Type of this endpoint's error logging policy.
Definition: endpoint.hpp:56