websocketpp  0.3.0
C++/Boost Asio based websocket client/server library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Public Types | Public Member Functions | Protected Member Functions | List of all members
websocketpp::connection< config > Class Template Reference

Represents an individual WebSocket connection. More...

#include <connection.hpp>

Inheritance diagram for websocketpp::connection< config >:

Public Types

typedef connection< config > type
 Type of this connection.
 
typedef lib::shared_ptr< typeptr
 Type of a shared pointer to this connection.
 
typedef lib::weak_ptr< typeweak_ptr
 Type of a weak pointer to this connection.
 
typedef config::concurrency_type concurrency_type
 Type of the concurrency component of this connection.
 
typedef config::alog_type alog_type
 Type of the access logging policy.
 
typedef config::elog_type elog_type
 Type of the error logging policy.
 
typedef
config::transport_type::transport_con_type 
transport_con_type
 Type of the transport component of this connection.
 
typedef transport_con_type::ptr transport_con_ptr
 Type of a shared pointer to the transport component of this connection.
 
typedef lib::function< void(ptr)> termination_handler
 
typedef
concurrency_type::scoped_lock_type 
scoped_lock_type
 
typedef
concurrency_type::mutex_type 
mutex_type
 
typedef config::request_type request_type
 
typedef config::response_type response_type
 
typedef config::message_type message_type
 
typedef message_type::ptr message_ptr
 
typedef
config::con_msg_manager_type 
con_msg_manager_type
 
typedef con_msg_manager_type::ptr con_msg_manager_ptr
 
typedef config::rng_type rng_type
 Type of RNG.
 
typedef processor::processor
< config > 
processor_type
 
typedef lib::shared_ptr
< processor_type
processor_ptr
 
typedef lib::function< void(connection_hdl,
message_ptr)> 
message_handler
 
typedef
transport_con_type::timer_ptr 
timer_ptr
 Type of a pointer to a transport timer handle.
 
typedef
session::internal_state::value 
istate_type
 

Public Member Functions

 connection (bool p_is_server, std::string const &ua, alog_type &alog, elog_type &elog, rng_type &rng)
 
ptr get_shared ()
 Get a shared pointer to this component.
 
void set_open_handler (open_handler h)
 Set open handler. More...
 
void set_close_handler (close_handler h)
 Set close handler. More...
 
void set_fail_handler (fail_handler h)
 Set fail handler. More...
 
void set_ping_handler (ping_handler h)
 Set ping handler. More...
 
void set_pong_handler (pong_handler h)
 Set pong handler. More...
 
void set_pong_timeout_handler (pong_timeout_handler h)
 Set pong timeout handler. More...
 
void set_interrupt_handler (interrupt_handler h)
 Set interrupt handler. More...
 
void set_http_handler (http_handler h)
 Set http handler. More...
 
void set_validate_handler (validate_handler h)
 Set validate handler. More...
 
void set_message_handler (message_handler h)
 Set message handler. More...
 
void set_open_handshake_timeout (long dur)
 Set open handshake timeout. More...
 
void set_close_handshake_timeout (long dur)
 Set close handshake timeout. More...
 
void set_pong_timeout (long dur)
 Set pong timeout. More...
 
size_t get_max_message_size () const
 Get maximum message size. More...
 
void set_max_message_size (size_t new_value)
 Set maximum message size. More...
 
size_t get_buffered_amount () const
 Get the size of the outgoing write buffer (in payload bytes) More...
 
size_t buffered_amount () const
 DEPRECATED: use get_buffered_amount instead.
 
lib::error_code send (std::string const &payload, frame::opcode::value op=frame::opcode::text)
 Create a message and then add it to the outgoing send queue. More...
 
lib::error_code send (void const *payload, size_t len, frame::opcode::value op=frame::opcode::binary)
 Send a message (raw array overload) More...
 
lib::error_code send (message_ptr msg)
 Add a message to the outgoing send queue. More...
 
lib::error_code interrupt ()
 Asyncronously invoke handler::on_inturrupt. More...
 
void handle_interrupt ()
 Transport inturrupt callback.
 
lib::error_code pause_reading ()
 Pause reading of new data. More...
 
void handle_pause_reading ()
 Pause reading callback. More...
 
lib::error_code resume_reading ()
 Resume reading of new data. More...
 
void handle_resume_reading ()
 Resume reading callback. More...
 
void ping (std::string const &payload)
 Send a ping. More...
 
void ping (std::string const &payload, lib::error_code &ec)
 exception free variant of ping
 
void handle_pong_timeout (std::string payload, lib::error_code const &ec)
 Utility method that gets called back when the ping timer expires.
 
void pong (std::string const &payload)
 Send a pong. More...
 
void pong (std::string const &payload, lib::error_code &ec)
 exception free variant of pong
 
void close (close::status::value const code, std::string const &reason)
 Close the connection. More...
 
void close (close::status::value const code, std::string const &reason, lib::error_code &ec)
 exception free variant of close
 
bool get_secure () const
 Returns the secure flag from the connection URI. More...
 
std::string const & get_host () const
 Returns the host component of the connection URI. More...
 
std::string const & get_resource () const
 Returns the resource component of the connection URI. More...
 
uint16_t get_port () const
 Returns the port component of the connection URI. More...
 
uri_ptr get_uri () const
 Gets the connection URI. More...
 
void set_uri (uri_ptr uri)
 Sets the connection URI. More...
 
std::string const & get_subprotocol () const
 Gets the negotated subprotocol. More...
 
std::vector< std::string > const & get_requested_subprotocols () const
 Gets all of the subprotocols requested by the client. More...
 
void add_subprotocol (std::string const &request, lib::error_code &ec)
 Adds the given subprotocol string to the request list (exception free) More...
 
void add_subprotocol (std::string const &request)
 Adds the given subprotocol string to the request list. More...
 
void select_subprotocol (std::string const &value, lib::error_code &ec)
 Select a subprotocol to use (exception free) More...
 
void select_subprotocol (std::string const &value)
 Select a subprotocol to use. More...
 
std::string const & get_request_header (std::string const &key)
 Retrieve a request header. More...
 
std::string const & get_response_header (std::string const &key)
 Retrieve a response header. More...
 
void set_status (http::status_code::value code)
 Set response status code and message. More...
 
void set_status (http::status_code::value code, std::string const &msg)
 Set response status code and message. More...
 
void set_body (std::string const &value)
 Set response body content. More...
 
void append_header (std::string const &key, std::string const &val)
 Append a header. More...
 
void replace_header (std::string const &key, std::string const &val)
 Replace a header. More...
 
void remove_header (std::string const &key)
 Remove a header. More...
 
request_type const & get_request () const
 Get request object. More...
 
connection_hdl get_handle () const
 Get Connection Handle. More...
 
bool is_server () const
 Get whether or not this connection is part of a server or client. More...
 
std::string const & get_origin () const
 Return the same origin policy origin value from the opening request. More...
 
session::state::value get_state () const
 Return the connection state. More...
 
close::status::value get_local_close_code () const
 Get the WebSocket close code sent by this endpoint. More...
 
std::string const & get_local_close_reason () const
 Get the WebSocket close reason sent by this endpoint. More...
 
close::status::value get_remote_close_code () const
 Get the WebSocket close code sent by the remote endpoint. More...
 
std::string const & get_remote_close_reason () const
 Get the WebSocket close reason sent by the remote endpoint. More...
 
lib::error_code get_ec () const
 Get the internal error code for a closed/failed connection. More...
 
void set_handle (connection_hdl hdl)
 Set Connection Handle. More...
 
message_ptr get_message (websocketpp::frame::opcode::value op, size_t size) const
 Get a message buffer. More...
 
void start ()
 
void read_handshake (size_t num_bytes)
 
void handle_read_handshake (lib::error_code const &ec, size_t bytes_transferred)
 
void handle_read_http_response (lib::error_code const &ec, size_t bytes_transferred)
 
void handle_send_http_response (lib::error_code const &ec)
 
void handle_send_http_request (lib::error_code const &ec)
 
void handle_open_handshake_timeout (lib::error_code const &ec)
 
void handle_close_handshake_timeout (lib::error_code const &ec)
 
void handle_read_frame (lib::error_code const &ec, size_t bytes_transferred)
 
void read_frame ()
 Issue a new transport read unless reading is paused.
 
const std::vector< int > & get_supported_versions () const
 Get array of WebSocket protocol versions that this connection supports.
 
void set_termination_handler (termination_handler new_handler)
 
void terminate (lib::error_code const &ec)
 
void handle_terminate (terminate_status tstat, lib::error_code const &ec)
 
void write_frame ()
 Checks if there are frames in the send queue and if there are sends one. More...
 
void handle_write_frame (lib::error_code const &ec)
 Process the results of a frame write operation and start the next write. More...
 

Protected Member Functions

void handle_transport_init (lib::error_code const &ec)
 
bool initialize_processor ()
 
bool process_handshake_request ()
 
void atomic_state_change (istate_type req, istate_type dest, std::string msg)
 Atomically change the internal connection state. More...
 
void atomic_state_change (istate_type ireq, istate_type idest, session::state::value ereq, session::state::value edest, std::string msg)
 Atomically change the internal and external connection state. More...
 
void atomic_state_check (istate_type req, std::string msg)
 Atomically read and compared the internal state. More...
 

Detailed Description

template<typename config>
class websocketpp::connection< config >

Represents an individual WebSocket connection.

Definition at line 221 of file connection.hpp.

Member Function Documentation

template<typename config >
void websocketpp::connection< config >::add_subprotocol ( std::string const &  request,
lib::error_code &  ec 
)

Adds the given subprotocol string to the request list (exception free)

Adds a subprotocol to the list to send with the opening handshake. This may be called multiple times to request more than one. If the server supports one of these, it may choose one. If so, it will return it in it's handshake reponse and the value will be available via get_subprotocol(). Subprotocol requests should be added in order of preference.

Parameters
requestThe subprotocol to request
ecA reference to an error code that will be filled in the case of errors

Definition at line 434 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::add_subprotocol ( std::string const &  request)

Adds the given subprotocol string to the request list.

Adds a subprotocol to the list to send with the opening handshake. This may be called multiple times to request more than one. If the server supports one of these, it may choose one. If so, it will return it in it's handshake reponse and the value will be available via get_subprotocol(). Subprotocol requests should be added in order of preference.

Parameters
requestThe subprotocol to request

Definition at line 454 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::append_header ( std::string const &  key,
std::string const &  val 
)

Append a header.

If a header with this name already exists the value will be appended to the existing header to form a comma separated list of values. Use connection::replace_header to overwrite existing values.

This member function is valid only from the http() and validate() handler callbacks, or to a client connection before connect has been called.

Parameters
keyName of the header to set
valValue to add
See also
replace_header
websocketpp::http::parser::append_header

Definition at line 554 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::atomic_state_change ( istate_type  req,
istate_type  dest,
std::string  msg 
)
protected

Atomically change the internal connection state.

Parameters
reqThe required starting state. If the internal state does not match req an exception is thrown.
destThe state to change to.
msgThe message to include in the exception thrown

Definition at line 1694 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::atomic_state_change ( istate_type  ireq,
istate_type  idest,
session::state::value  ereq,
session::state::value  edest,
std::string  msg 
)
protected

Atomically change the internal and external connection state.

Parameters
ireqThe required starting internal state. If the internal state does not match ireq an exception is thrown.
idestThe internal state to change to.
ereqThe required starting external state. If the external state does not match ereq an exception is thrown.
edestThe external state to change to.
msgThe message to include in the exception thrown

Definition at line 1708 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::atomic_state_check ( istate_type  req,
std::string  msg 
)
protected

Atomically read and compared the internal state.

Parameters
reqThe state to test against. If the internal state does not match req an exception is thrown.
msgThe message to include in the exception thrown

Definition at line 1724 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::close ( close::status::value const  code,
std::string const &  reason 
)

Close the connection.

Initiates the close handshake process.

If close returns successfully the connection will be in the closing state and no additional messages may be sent. All messages sent prior to calling close will be written out before the connection is closed.

If no reason is specified none will be sent. If no code is specified then no code will be sent.

The handler's on_close callback will be called once the close handshake is complete.

Reasons will be automatically truncated to the maximum length (123 bytes) if necessary.

Parameters
codeThe close code to send
reasonThe close reason to send

Definition at line 302 of file connection_impl.hpp.

template<typename config >
size_t websocketpp::connection< config >::get_buffered_amount ( ) const

Get the size of the outgoing write buffer (in payload bytes)

Retrieves the number of bytes in the outgoing write buffer that have not already been dispatched to the transport layer. This represents the bytes that are presently cancelable without uncleanly ending the websocket connection

This method invokes the m_write_lock mutex

Returns
The current number of bytes in the outgoing send buffer.

Definition at line 64 of file connection_impl.hpp.

template<typename config>
lib::error_code websocketpp::connection< config >::get_ec ( ) const
inline

Get the internal error code for a closed/failed connection.

Retrieves a machine readable detailed error code indicating the reason that the connection was closed or failed. Valid only after the close or fail handler is called.

Returns
Error code indicating the reason the connection was closed or failed

Definition at line 1103 of file connection.hpp.

template<typename config>
connection_hdl websocketpp::connection< config >::get_handle ( ) const
inline

Get Connection Handle.

The connection handle is a token that can be shared outside the WebSocket++ core for the purposes of identifying a connection and sending it messages.

Returns
A handle to the connection

Definition at line 1032 of file connection.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_host ( ) const

Returns the host component of the connection URI.

This value is available after the HTTP request has been fully read and may be called from any thread.

Returns
The host component of the connection URI

Definition at line 388 of file connection_impl.hpp.

template<typename config>
close::status::value websocketpp::connection< config >::get_local_close_code ( ) const
inline

Get the WebSocket close code sent by this endpoint.

Returns
The WebSocket close code sent by this endpoint.

Definition at line 1066 of file connection.hpp.

template<typename config>
std::string const& websocketpp::connection< config >::get_local_close_reason ( ) const
inline

Get the WebSocket close reason sent by this endpoint.

Returns
The WebSocket close reason sent by this endpoint.

Definition at line 1074 of file connection.hpp.

template<typename config>
size_t websocketpp::connection< config >::get_max_message_size ( ) const
inline

Get maximum message size.

Get maximum message size. Maximum message size determines the point at which the connection will fail a connection with the message_too_big protocol error.

The default is set by the endpoint that creates the connection.

Since
0.3.0

Definition at line 543 of file connection.hpp.

template<typename config>
message_ptr websocketpp::connection< config >::get_message ( websocketpp::frame::opcode::value  op,
size_t  size 
) const
inline

Get a message buffer.

Warning: The API related to directly sending message buffers may change before the 1.0 release. If you plan to use it, please keep an eye on any breaking changes notifications in future release notes. Also if you have any feedback about usage and capabilities now is a great time to provide it.

Message buffers are used to store message payloads and other message metadata.

The size parameter is a hint only. Your final payload does not need to match it. There may be some performance benefits if the initial size guess is equal to or slightly higher than the final payload size.

Parameters
opThe opcode for the new message
sizeA hint to optimize the initial allocation of payload space.
Returns
A new message buffer

Definition at line 1146 of file connection.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_origin ( ) const

Return the same origin policy origin value from the opening request.

This value is available after the HTTP request has been fully read and may be called from any thread.

Returns
The connection's origin value from the opening handshake.

Definition at line 58 of file connection_impl.hpp.

template<typename config >
uint16_t websocketpp::connection< config >::get_port ( ) const

Returns the port component of the connection URI.

This value is available after the HTTP request has been fully read and may be called from any thread.

Returns
The port component of the connection URI

Definition at line 400 of file connection_impl.hpp.

template<typename config>
close::status::value websocketpp::connection< config >::get_remote_close_code ( ) const
inline

Get the WebSocket close code sent by the remote endpoint.

Returns
The WebSocket close code sent by the remote endpoint.

Definition at line 1082 of file connection.hpp.

template<typename config>
std::string const& websocketpp::connection< config >::get_remote_close_reason ( ) const
inline

Get the WebSocket close reason sent by the remote endpoint.

Returns
The WebSocket close reason sent by the remote endpoint.

Definition at line 1090 of file connection.hpp.

template<typename config>
request_type const& websocketpp::connection< config >::get_request ( ) const
inline

Get request object.

Direct access to request object. This can be used to call methods of the request object that are not part of the standard request API that connection wraps.

Note use of this method involves using behavior specific to the configured HTTP policy. Such behavior may not work with alternate HTTP policies.

Since
0.3.0-alpha3
Returns
A const reference to the raw request object

Definition at line 1016 of file connection.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_request_header ( std::string const &  key)

Retrieve a request header.

Retrieve the value of a header from the handshake HTTP request.

Parameters
keyName of the header to get
Returns
The value of the header

Definition at line 503 of file connection_impl.hpp.

template<typename config >
const std::vector< std::string > & websocketpp::connection< config >::get_requested_subprotocols ( ) const

Gets all of the subprotocols requested by the client.

Retrieves the subprotocols that were requested during the handshake. This method is valid in the validate handler and later.

Returns
A vector of the requested subprotocol

Definition at line 429 of file connection_impl.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_resource ( ) const

Returns the resource component of the connection URI.

This value is available after the HTTP request has been fully read and may be called from any thread.

Returns
The resource component of the connection URI

Definition at line 394 of file connection_impl.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_response_header ( std::string const &  key)

Retrieve a response header.

Retrieve the value of a header from the handshake HTTP request.

Parameters
keyName of the header to get
Returns
The value of the header

Definition at line 509 of file connection_impl.hpp.

template<typename config >
bool websocketpp::connection< config >::get_secure ( ) const

Returns the secure flag from the connection URI.

This value is available after the HTTP request has been fully read and may be called from any thread.

Returns
Whether or not the connection URI is flagged secure.

Definition at line 382 of file connection_impl.hpp.

template<typename config >
session::state::value websocketpp::connection< config >::get_state ( ) const

Return the connection state.

Values can be connecting, open, closing, and closed

Returns
The connection's current state.

Definition at line 70 of file connection_impl.hpp.

template<typename config >
const std::string & websocketpp::connection< config >::get_subprotocol ( ) const

Gets the negotated subprotocol.

Retrieves the subprotocol that was negotiated during the handshake. This method is valid in the open handler and later.

Returns
The negotiated subprotocol

Definition at line 423 of file connection_impl.hpp.

template<typename config >
uri_ptr websocketpp::connection< config >::get_uri ( ) const

Gets the connection URI.

This should really only be called by internal library methods unless you really know what you are doing.

Returns
A pointer to the connection's URI

Definition at line 406 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::handle_pause_reading ( )

Pause reading callback.

Pause reading handler. Not safe to call directly.

Definition at line 348 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::handle_resume_reading ( )

Resume reading callback.

Resume reading helper method. Not safe to call directly.

Definition at line 366 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::handle_write_frame ( lib::error_code const &  ec)

Process the results of a frame write operation and start the next write.

Todo:
unit tests

This method locks the m_write_lock mutex

Parameters
terminateWhether or not to terminate the connection upon completion of this write.
ecA status code from the transport layer, zero on success, non-zero otherwise.

Definition at line 1652 of file connection_impl.hpp.

template<typename config >
bool websocketpp::connection< config >::initialize_processor ( )
protected

Set m_processor based on information in m_request. Set m_response status and return false on error.

Definition at line 1015 of file connection_impl.hpp.

template<typename config >
lib::error_code websocketpp::connection< config >::interrupt ( )

Asyncronously invoke handler::on_inturrupt.

Trigger the on_interrupt handler.

Signals to the connection to asyncronously invoke the on_inturrupt callback for this connection's handler once it is safe to do so.

When the on_inturrupt handler callback is called it will be from within the transport event loop with all the thread safety features guaranteed by the transport to regular handlers

Multiple inturrupt signals can be active at once on the same connection

Returns
An error code

This is thread safe if the transport is thread safe

Definition at line 317 of file connection_impl.hpp.

template<typename config>
bool websocketpp::connection< config >::is_server ( ) const
inline

Get whether or not this connection is part of a server or client.

Returns
whether or not the connection is attached to a server endpoint

Definition at line 1040 of file connection.hpp.

template<typename config >
lib::error_code websocketpp::connection< config >::pause_reading ( )

Pause reading of new data.

Signals to the connection to halt reading of new data. While reading is paused, the connection will stop reading from its associated socket. In turn this will result in TCP based flow control kicking in and slowing data flow from the remote endpoint.

This is useful for applications that push new requests to a queue to be processed by another thread and need a way to signal when their request queue is full without blocking the network processing thread.

Use resume_reading() to resume.

If supported by the transport this is done asynchronously. As such reading may not stop until the current read operation completes. Typically you can expect to receive no more bytes after initiating a read pause than the size of the read buffer.

If reading is paused for this connection already nothing is changed.

Definition at line 336 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::ping ( std::string const &  payload)

Send a ping.

Initiates a ping with the given payload/

There is no feedback directly from ping except in cases of immediately detectable errors. Feedback will be provided via on_pong or on_pong_timeout callbacks.

Ping locks the m_write_lock mutex

Parameters
payloadPayload to be used for the ping

Definition at line 208 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::pong ( std::string const &  payload)

Send a pong.

Initiates a pong with the given payload.

There is no feedback from a pong once sent.

Pong locks the m_write_lock mutex

Parameters
payloadPayload to be used for the pong

Definition at line 273 of file connection_impl.hpp.

template<typename config >
bool websocketpp::connection< config >::process_handshake_request ( )
protected

Perform WebSocket handshake validation of m_request using m_processor. set m_response and return false on error.

Definition at line 1057 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::remove_header ( std::string const &  key)

Remove a header.

Removes a header from the response.

This member function is valid only from the http() and validate() handler callbacks, or to a client connection before connect has been called.

Parameters
keyThe name of the header to remove
See also
websocketpp::http::parser::remove_header

Definition at line 598 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::replace_header ( std::string const &  key,
std::string const &  val 
)

Replace a header.

If a header with this name already exists the old value will be replaced Use connection::append_header to append to a list of existing values.

This member function is valid only from the http() and validate() handler callbacks, or to a client connection before connect has been called.

Parameters
keyName of the header to set
valValue to set
See also
append_header
websocketpp::http::parser::replace_header

Definition at line 576 of file connection_impl.hpp.

template<typename config >
lib::error_code websocketpp::connection< config >::resume_reading ( )

Resume reading of new data.

Signals to the connection to resume reading of new data after it was paused by pause_reading().

If reading is not paused for this connection already nothing is changed.

Definition at line 354 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::select_subprotocol ( std::string const &  value,
lib::error_code &  ec 
)

Select a subprotocol to use (exception free)

Indicates which subprotocol should be used for this connection. Valid only during the validate handler callback. Subprotocol selected must have been requested by the client. Consult get_requested_subprotocols() for a list of valid subprotocols.

This member function is valid on server endpoints/connections only

Parameters
valueThe subprotocol to select
ecA reference to an error code that will be filled in the case of errors

Definition at line 464 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::select_subprotocol ( std::string const &  value)

Select a subprotocol to use.

Indicates which subprotocol should be used for this connection. Valid only during the validate handler callback. Subprotocol selected must have been requested by the client. Consult get_requested_subprotocols() for a list of valid subprotocols.

This member function is valid on server endpoints/connections only

Parameters
valueThe subprotocol to select

Definition at line 492 of file connection_impl.hpp.

template<typename config >
lib::error_code websocketpp::connection< config >::send ( std::string const &  payload,
frame::opcode::value  op = frame::opcode::text 
)

Create a message and then add it to the outgoing send queue.

Convenience method to send a message given a payload string and optionally an opcode. Default opcode is utf8 text.

This method locks the m_write_lock mutex

Parameters
payloadThe payload string to generated the message with
opThe opcode to generated the message with. Default is frame::opcode::text

Definition at line 76 of file connection_impl.hpp.

template<typename config >
lib::error_code websocketpp::connection< config >::send ( void const *  payload,
size_t  len,
frame::opcode::value  op = frame::opcode::binary 
)

Send a message (raw array overload)

Convenience method to send a message given a raw array and optionally an opcode. Default opcode is binary.

This method locks the m_write_lock mutex

Parameters
payloadA pointer to the array containing the bytes to send.
lenLength of the array.
opThe opcode to generated the message with. Default is frame::opcode::binary

Definition at line 86 of file connection_impl.hpp.

template<typename config>
lib::error_code websocketpp::connection< config >::send ( message_ptr  msg)

Add a message to the outgoing send queue.

If presented with a prepared message it is added without validation or framing. If presented with an unprepared message it is validated, framed, and then added

Errors are returned via an exception

Todo:
make exception system_error rather than error_code

This method invokes the m_write_lock mutex

Parameters
msgA message_ptr to the message to send.
template<typename config >
void websocketpp::connection< config >::set_body ( std::string const &  value)

Set response body content.

Set the body content of the HTTP response to the parameter string. Note set_body will also set the Content-Length HTTP header to the appropriate value. If you want the Content-Length header to be something else set it to something else after calling set_body

This member function is valid only from the http() and validate() handler callbacks.

Parameters
valueString data to include as the body content.
See also
websocketpp::http::response::set_body

Definition at line 541 of file connection_impl.hpp.

template<typename config>
void websocketpp::connection< config >::set_close_handler ( close_handler  h)
inline

Set close handler.

The close handler is called immediately after the connection is closed.

Parameters
hThe new close_handler

Definition at line 345 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_close_handshake_timeout ( long  dur)
inline

Set close handshake timeout.

Sets the length of time the library will wait after a closing handshake has been initiated before cancelling it. This can be used to prevent excessive wait times for outgoing clients or excessive resource usage from broken clients or DoS attacks on servers.

Connections that time out will have their close handlers called with the close_handshake_timeout error code.

The default value is specified via the compile time config value 'timeout_close_handshake'. The default value in the core config is 5000ms. A value of 0 will disable the timer entirely.

To be effective, the transport you are using must support timers. See the documentation for your transport policy for details about its timer support.

Parameters
durThe length of the close handshake timeout in ms

Definition at line 509 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_fail_handler ( fail_handler  h)
inline

Set fail handler.

The fail handler is called whenever the connection fails while the handshake is bring processed.

Parameters
hThe new fail_handler

Definition at line 356 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_handle ( connection_hdl  hdl)
inline

Set Connection Handle.

The connection handle is a token that can be shared outside the WebSocket++ core for the purposes of identifying a connection and sending it messages.

Parameters
hdlA connection_hdl that the connection will use to refer to itself.

Definition at line 1122 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_http_handler ( http_handler  h)
inline

Set http handler.

The http handler is called after an HTTP request other than a WebSocket upgrade request is received. It allows a WebSocket++ server to respond to regular HTTP requests on the same port as it processes WebSocket connections. This can be useful for hosting error messages, flash policy files, status pages, and other simple HTTP responses. It is not intended to be used as a primary web server.

Parameters
hThe new http_handler

Definition at line 431 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_interrupt_handler ( interrupt_handler  h)
inline

Set interrupt handler.

The interrupt handler is called whenever the connection is manually interrupted by the application.

Parameters
hThe new interrupt_handler

Definition at line 416 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_max_message_size ( size_t  new_value)
inline

Set maximum message size.

Set maximum message size. Maximum message size determines the point at which the connection will fail a connection with the message_too_big protocol error. This value may be changed during the connection.

The default is set by the endpoint that creates the connection.

Since
0.3.0
Parameters
new_valueThe value to set as the maximum message size.

Definition at line 559 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_message_handler ( message_handler  h)
inline

Set message handler.

The message handler is called after a new message has been received.

Parameters
hThe new message_handler

Definition at line 457 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_open_handler ( open_handler  h)
inline

Set open handler.

The open handler is called after the WebSocket handshake is complete and the connection is considered OPEN.

Parameters
hThe new open_handler

Definition at line 335 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_open_handshake_timeout ( long  dur)
inline

Set open handshake timeout.

Sets the length of time the library will wait after an opening handshake has been initiated before cancelling it. This can be used to prevent excessive wait times for outgoing clients or excessive resource usage from broken clients or DoS attacks on servers.

Connections that time out will have their fail handlers called with the open_handshake_timeout error code.

The default value is specified via the compile time config value 'timeout_open_handshake'. The default value in the core config is 5000ms. A value of 0 will disable the timer entirely.

To be effective, the transport you are using must support timers. See the documentation for your transport policy for details about its timer support.

Parameters
durThe length of the open handshake timeout in ms

Definition at line 485 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_ping_handler ( ping_handler  h)
inline

Set ping handler.

The ping handler is called whenever the connection receives a ping control frame. The ping payload is included.

The ping handler's return time controls whether or not a pong is sent in response to this ping. Returning false will suppress the return pong. If no ping handler is set a pong will be sent.

Parameters
hThe new ping_handler

Definition at line 371 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_pong_handler ( pong_handler  h)
inline

Set pong handler.

The pong handler is called whenever the connection receives a pong control frame. The pong payload is included.

Parameters
hThe new pong_handler

Definition at line 382 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_pong_timeout ( long  dur)
inline

Set pong timeout.

Sets the length of time the library will wait for a pong response to a ping. This can be used as a keepalive or to detect broken connections.

Pong responses that time out will have the pong timeout handler called.

The default value is specified via the compile time config value 'timeout_pong'. The default value in the core config is 5000ms. A value of 0 will disable the timer entirely.

To be effective, the transport you are using must support timers. See the documentation for your transport policy for details about its timer support.

Parameters
durThe length of the pong timeout in ms

Definition at line 530 of file connection.hpp.

template<typename config>
void websocketpp::connection< config >::set_pong_timeout_handler ( pong_timeout_handler  h)
inline

Set pong timeout handler.

If the transport component being used supports timers, the pong timeout handler is called whenever a pong control frame is not received with the configured timeout period after the application sends a ping.

The config setting timeout_pong controls the length of the timeout period. It is specified in milliseconds.

This can be used to probe the health of the remote endpoint's WebSocket implementation. This does not guarantee that the remote application itself is still healthy but can be a useful diagnostic.

Note: receipt of this callback doesn't mean the pong will never come. This functionality will not suppress delivery of the pong in question should it arrive after the timeout.

Parameters
hThe new pong_timeout_handler

Definition at line 405 of file connection.hpp.

template<typename config >
void websocketpp::connection< config >::set_status ( http::status_code::value  code)

Set response status code and message.

Sets the response status code to code and looks up the corresponding message for standard codes. Non-standard codes will be entered as Unknown use set_status(status_code::value,std::string) overload to set both values explicitly.

This member function is valid only from the http() and validate() handler callbacks.

Parameters
codeCode to set
msgMessage to set
See also
websocketpp::http::response::set_status

Definition at line 514 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::set_status ( http::status_code::value  code,
std::string const &  msg 
)

Set response status code and message.

Sets the response status code and message to independent custom values. use set_status(status_code::value) to set the code and have the standard message be automatically set.

This member function is valid only from the http() and validate() handler callbacks.

Parameters
codeCode to set
msgMessage to set
See also
websocketpp::http::response::set_status

Definition at line 527 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::set_termination_handler ( termination_handler  new_handler)

Sets the handler for a terminating connection. Should only be used internally by the endpoint class.

Definition at line 46 of file connection_impl.hpp.

template<typename config >
void websocketpp::connection< config >::set_uri ( uri_ptr  uri)

Sets the connection URI.

This should really only be called by internal library methods unless you really know what you are doing.

Parameters
uriThe new URI to set

Definition at line 412 of file connection_impl.hpp.

template<typename config>
void websocketpp::connection< config >::set_validate_handler ( validate_handler  h)
inline

Set validate handler.

The validate handler is called after a WebSocket handshake has been parsed but before a response is returned. It provides the application a chance to examine the request and determine whether or not it wants to accept the connection.

Returning false from the validate handler will reject the connection. If no validate handler is present, all connections will be allowed.

Parameters
hThe new validate_handler

Definition at line 447 of file connection.hpp.

template<typename config >
void websocketpp::connection< config >::write_frame ( )

Checks if there are frames in the send queue and if there are sends one.

Todo:
unit tests

This method locks the m_write_lock mutex

Definition at line 1559 of file connection_impl.hpp.


The documentation for this class was generated from the following files: