Loading...
Searching...
No Matches
websocketpp::transport::iostream::connection< config > Class Template Reference
Inheritance diagram for websocketpp::transport::iostream::connection< config >:

## Public Types

typedef connection< config > | type
| Type of this connection transport component.
typedef lib::shared_ptr< type > | ptr
| Type of a shared pointer to this connection transport component.
typedef config::concurrency_type | concurrency_type
| transport concurrency policy
typedef config::alog_type | alog_type
| Type of this transport's access logging policy.
typedef config::elog_type | elog_type
| Type of this transport's error logging policy.
typedef concurrency_type::scoped_lock_type | scoped_lock_type
typedef concurrency_type::mutex_type | mutex_type
typedef lib::shared_ptr< timer > | timer_ptr

## Public Member Functions

| connection (bool is_server, const lib::shared_ptr< alog_type > &alog, const lib::shared_ptr< elog_type > &elog)
ptr | get_shared ()
| Get a shared pointer to this component.
void | register_ostream (std::ostream *o)
| Register a std::ostream with the transport for writing output.
void | set_uri (uri_ptr)
| Set uri hook.
size_t | read_some (char const *buf, size_t len)
| Manual input supply (read some).
size_t | read_all (char const *buf, size_t len)
| Manual input supply (read all).
size_t | readsome (char const *buf, size_t len)
| Manual input supply (DEPRECATED).
void | eof ()
| Signal EOF.
void | fatal_error ()
| Signal transport error.
void | set_secure (bool value)
| Set whether or not this connection is secure.
bool | is_secure () const
| Tests whether or not the underlying transport is secure.
void | set_remote_endpoint (std::string value)
| Set human readable remote endpoint address.
std::string | get_remote_endpoint () const
| Get human readable remote endpoint address.
connection_hdl | get_handle () const
| Get the connection handle.
timer_ptr | set_timer (long, timer_handler)
| Call back a function after a period of time.
void | set_write_handler (write_handler h)
| Sets the write handler.
void | set_vector_write_handler (vector_write_handler h)
| Sets the vectored write handler.
void | set_shutdown_handler (shutdown_handler h)
| Sets the shutdown handler.

## Protected Member Functions

void | init (init_handler handler)
| Initialize the connection transport.
void | async_read_at_least (size_t num_bytes, char *buf, size_t len, read_handler handler)
| Initiate an async_read for at least num_bytes bytes into buf.
void | async_write (char const *buf, size_t len, transport::write_handler handler)
| Asyncronous Transport Write.
void | async_write (std::vector< buffer > const &bufs, transport::write_handler handler)
| Asyncronous Transport Write (scatter-gather).
void | set_handle (connection_hdl hdl)
| Set Connection Handle.
lib::error_code | dispatch (dispatch_handler handler)
| Call given handler back within the transport's event system (if present).
void | async_shutdown (transport::shutdown_handler handler)
| Perform cleanup on socket shutdown_handler.

## Friends

std::istream & | operator>> (std::istream &in, type &t)
| Overloaded stream input operator.

## Detailed Description

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

Definition at line 60 of file connection.hpp.

## Member Typedef Documentation

## alog_type

template<typename config>

typedef config::alog_type websocketpp::transport::iostream::connection< config >::alog_type

Type of this transport's access logging policy.

Definition at line 70 of file connection.hpp.

## concurrency_type

template<typename config>

typedef config::concurrency_type websocketpp::transport::iostream::connection< config >::concurrency_type

transport concurrency policy

Definition at line 68 of file connection.hpp.

## elog_type

template<typename config>

typedef config::elog_type websocketpp::transport::iostream::connection< config >::elog_type

Type of this transport's error logging policy.

Definition at line 72 of file connection.hpp.

## mutex_type

template<typename config>

typedef concurrency_type::mutex_type websocketpp::transport::iostream::connection< config >::mutex_type

Definition at line 76 of file connection.hpp.

## ptr

template<typename config>

typedef lib::shared_ptr<type> websocketpp::transport::iostream::connection< config >::ptr

Type of a shared pointer to this connection transport component.

Definition at line 65 of file connection.hpp.

## scoped_lock_type

template<typename config>

typedef concurrency_type::scoped_lock_type websocketpp::transport::iostream::connection< config >::scoped_lock_type

Definition at line 75 of file connection.hpp.

## timer_ptr

template<typename config>

typedef lib::shared_ptr<timer> websocketpp::transport::iostream::connection< config >::timer_ptr

Definition at line 78 of file connection.hpp.

## type

template<typename config>

typedef connection<config> websocketpp::transport::iostream::connection< config >::type

Type of this connection transport component.

Definition at line 63 of file connection.hpp.

## Constructor & Destructor Documentation

## connection()

template<typename config>

websocketpp::transport::iostream::connection< config >::connection | ( | bool | is_server,
|  | const lib::shared_ptr< alog_type > & | alog,
|  | const lib::shared_ptr< elog_type > & | elog )

inline explicit

Definition at line 80 of file connection.hpp.

## Member Function Documentation

## async_read_at_least()

template<typename config>

void websocketpp::transport::iostream::connection< config >::async_read_at_least | ( | size_t | num_bytes,
|  | char * | buf,
|  | size_t | len,
|  | read_handler | handler )

inline protected

Initiate an async_read for at least num_bytes bytes into buf.

Initiates an async_read request for at least num_bytes bytes. The input will be read into buf. A maximum of len bytes will be input. When the operation is complete, handler will be called with the status and number of bytes read.

This method may or may not call handler from within the initial call. The application should be prepared to accept either.

The application should never call this method a second time before it has been called back for the first read. If this is done, the second read will be called back immediately with a double_read error.

If num_bytes or len are zero handler will be called back immediately indicating success.

Parameters

  num_bytes | Don't call handler until at least this many bytes have been read.
  buf | The buffer to read bytes into
  len | The size of buf. At maximum, this many bytes will be read.
  handler | The callback to invoke when the operation is complete or ends in an error

Definition at line 439 of file connection.hpp.

## async_shutdown()

template<typename config>

void websocketpp::transport::iostream::connection< config >::async_shutdown | ( | transport::shutdown_handler | handler | ) |

inline protected

Perform cleanup on socket shutdown_handler.

If a shutdown handler is set, call it and pass through its return error code. Otherwise assume there is nothing to do and pass through a success code.

Parameters

  handler | The shutdown_handler to call back when complete

Definition at line 593 of file connection.hpp.

## async_write() [1/2]

template<typename config>

void websocketpp::transport::iostream::connection< config >::async_write | ( | char const * | buf,
|  | size_t | len,
|  | transport::write_handler | handler )

inline protected

Asyncronous Transport Write.

Write len bytes in buf to the output method. Call handler to report success or failure. handler may or may not be called during async_write, but it must be safe for this to happen.

Will return 0 on success. Other possible errors (not exhaustive) output_stream_required: No output stream was registered to write to bad_stream: a ostream pass through error

This method will attempt to write to the registered ostream first. If an ostream is not registered it will use the write handler. If neither are registered then an error is passed up to the connection.

Parameters

  buf | buffer to read bytes from
  len | number of bytes to write
  handler | Callback to invoke with operation status.

Definition at line 487 of file connection.hpp.

## async_write() [2/2]

template<typename config>

void websocketpp::transport::iostream::connection< config >::async_write | ( | std::vector< buffer > const & | bufs,
|  | transport::write_handler | handler )

inline protected

Asyncronous Transport Write (scatter-gather).

Write a sequence of buffers to the output method. Call handler to report success or failure. handler may or may not be called during async_write, but it must be safe for this to happen.

Will return 0 on success. Other possible errors (not exhaustive) output_stream_required: No output stream was registered to write to bad_stream: a ostream pass through error

This method will attempt to write to the registered ostream first. If an ostream is not registered it will use the write handler. If neither are registered then an error is passed up to the connection.

Parameters

  bufs | vector of buffers to write
  handler | Callback to invoke with operation status.

Definition at line 527 of file connection.hpp.

## dispatch()

template<typename config>

lib::error_code websocketpp::transport::iostream::connection< config >::dispatch | ( | dispatch_handler | handler | ) |

inline protected

Call given handler back within the transport's event system (if present).

Invoke a callback within the transport's event system if it has one. If it doesn't, the handler will be invoked immediately before this function returns.

Parameters

  handler | The callback to invoke

Returns
  Whether or not the transport was able to register the handler for callback.

Definition at line 580 of file connection.hpp.

## eof()

template<typename config>

void websocketpp::transport::iostream::connection< config >::eof | ( |  | ) |

inline

Signal EOF.

Signals to the transport that data stream being read has reached EOF and that no more bytes may be read or written to/from the transport.

Since
  0.3.0-alpha4

Definition at line 219 of file connection.hpp.

## fatal_error()

template<typename config>

void websocketpp::transport::iostream::connection< config >::fatal_error | ( |  | ) |

inline

Signal transport error.

Signals to the transport that a fatal data stream error has occurred and that no more bytes may be read or written to/from the transport.

Since
  0.3.0-alpha4

Definition at line 235 of file connection.hpp.

## get_handle()

template<typename config>

connection_hdl websocketpp::transport::iostream::connection< config >::get_handle | ( |  | ) | const

inline

Get the connection handle.

Returns
  The handle for this connection.

Definition at line 313 of file connection.hpp.

## get_remote_endpoint()

template<typename config>

std::string websocketpp::transport::iostream::connection< config >::get_remote_endpoint | ( |  | ) | const

inline

Get human readable remote endpoint address.

The iostream transport has no information about the ultimate remote endpoint. It will return the string "iostream transport". The set_remote_endpoint method may be used by external network code to set a more accurate value.

This value is used in access and error logs and is available to the end application for including in user facing interfaces and messages.

Returns
  A string identifying the address of the remote endpoint

Definition at line 305 of file connection.hpp.

## get_shared()

template<typename config>

ptr websocketpp::transport::iostream::connection< config >::get_shared | ( |  | ) |

inline

Get a shared pointer to this component.

Definition at line 93 of file connection.hpp.

## init()

template<typename config>

void websocketpp::transport::iostream::connection< config >::init | ( | init_handler | handler | ) |

inline protected

Initialize the connection transport.

Initialize the connection's transport component.

Parameters

  handler | The init_handler to call when initialization is done

Definition at line 410 of file connection.hpp.

## is_secure()

template<typename config>

bool websocketpp::transport::iostream::connection< config >::is_secure | ( |  | ) | const

inline

Tests whether or not the underlying transport is secure.

iostream transport will return false always because it has no information about the ultimate remote endpoint. This may or may not be accurate depending on the real source of bytes being input. The set_secure method may be used to flag connections that are secured by an external API

Returns
  Whether or not the underlying transport is secure

Definition at line 271 of file connection.hpp.

## read_all()

template<typename config>

size_t websocketpp::transport::iostream::connection< config >::read_all | ( | char const * | buf,
|  | size_t | len )

inline

Manual input supply (read all).

Similar to read_some, but continues to read until all bytes in the supplied buffer have been read or the connection runs out of read requests.

This method still may not read all of the bytes in the input buffer. if it doesn't it indicates that the connection was most likely closed or is in an error state where it is no longer accepting new input.

Since
  0.3.0

Parameters

  buf | Char buffer to read into the websocket
  len | Length of buf

Returns
  The number of characters from buf actually read.

Definition at line 188 of file connection.hpp.

## read_some()

template<typename config>

size_t websocketpp::transport::iostream::connection< config >::read_some | ( | char const * | buf,
|  | size_t | len )

inline

Manual input supply (read some).

Copies bytes from buf into WebSocket++'s input buffers. Bytes will be copied from the supplied buffer to fulfill any pending library reads. It will return the number of bytes successfully processed. If there are no pending reads read_some will return immediately. Not all of the bytes may be able to be read in one call.

Since
  0.3.0-alpha4

Parameters

  buf | Char buffer to read into the websocket
  len | Length of buf

Returns
  The number of characters from buf actually read.

Definition at line 165 of file connection.hpp.

## readsome()

template<typename config>

size_t websocketpp::transport::iostream::connection< config >::readsome | ( | char const * | buf,
|  | size_t | len )

inline

Manual input supply (DEPRECATED).

Deprecated
  DEPRECATED in favor of read_some()

See also
  read_some()

Definition at line 208 of file connection.hpp.

## register_ostream()

template<typename config>

void websocketpp::transport::iostream::connection< config >::register_ostream | ( | std::ostream * | o | ) |

inline

Register a std::ostream with the transport for writing output.

Register a std::ostream with the transport. All future writes will be done to this output stream.

Parameters

  o | A pointer to the ostream to use for output.

Definition at line 104 of file connection.hpp.

## set_handle()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_handle | ( | connection_hdl | hdl | ) |

inline protected

Set Connection Handle.

Parameters

  hdl | The new handle

Definition at line 565 of file connection.hpp.

## set_remote_endpoint()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_remote_endpoint | ( | std::string | value | ) |

inline

Set human readable remote endpoint address.

Sets the remote endpoint address returned by get_remote_endpoint. This value should be a human readable string that describes the remote endpoint. Typically an IP address or hostname, perhaps with a port. But may be something else depending on the nature of the underlying transport.

If none is set the default is "iostream transport".

Since
  0.3.0-alpha4

Parameters

  value | The remote endpoint address to set.

Definition at line 289 of file connection.hpp.

## set_secure()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_secure | ( | bool | value | ) |

inline

Set whether or not this connection is secure.

The iostream transport does not provide any security features. As such it defaults to returning false when is_secure is called. However, the iostream transport may be used to wrap an external socket API that may provide secure transport. This method allows that external API to flag whether or not this connection is secure so that users of the WebSocket++ API will get more accurate information.

Since
  0.3.0-alpha4

Parameters

  value | Whether or not this connection is secure.

Definition at line 257 of file connection.hpp.

## set_shutdown_handler()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_shutdown_handler | ( | shutdown_handler | h | ) |

inline

Sets the shutdown handler.

The shutdown handler is called when the iostream transport receives a notification from the core library that it is finished with all read and write operations and that the underlying transport can be cleaned up.

If you are using iostream transport with another socket library, this is a good time to close/shutdown the socket for this connection.

The signature of the handler is lib::error_code (connection_hdl). The code returned will be reported and logged by the core library.

Since
  0.5.0

Parameters

  h | The handler to call on connection shutdown.

Definition at line 400 of file connection.hpp.

## set_timer()

template<typename config>

timer_ptr websocketpp::transport::iostream::connection< config >::set_timer | ( | long | ,
|  | timer_handler | )

inline

Call back a function after a period of time.

Timers are not implemented in this transport. The timer pointer will always be empty. The handler will never be called.

Parameters

  duration | Length of time to wait in milliseconds
  callback | The function to call back when the timer has expired

Returns
  A handle that can be used to cancel the timer if it is no longer needed.

Definition at line 327 of file connection.hpp.

## set_uri()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_uri | ( | uri_ptr |  | ) |

inline

Set uri hook.

Called by the endpoint as a connection is being established to provide the uri being connected to to the transport layer.

This transport policy doesn't use the uri so it is ignored.

Since
  0.6.0

Parameters

  u | The uri to set

Definition at line 121 of file connection.hpp.

## set_vector_write_handler()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_vector_write_handler | ( | vector_write_handler | h | ) |

inline

Sets the vectored write handler.

The vectored write handler is called when the iostream transport receives multiple chunks of data that need to be written to the appropriate output location. This handler can be used in conjunction with the write_handler in place of registering an ostream for output.

The sequence of buffers represents bytes that should be written consecutively and it is suggested to group the buffers into as few next layer packets as possible. Vector write is used to allow implementations that support it to coalesce writes into a single TCP packet or TLS segment for improved efficiency.

This is an optional handler. If it is not defined then multiple calls will be made to the standard write handler.

The signature of the handler is lib::error_code (connection_hdl, std::vector<websocketpp::transport::buffer> const & bufs). The code returned will be reported and logged by the core library. The websocketpp::transport::buffer type is a struct with two data members. buf (char const *) and len (size_t).

Since
  0.6.0

Parameters

  h | The handler to call when vectored data is to be written.

Definition at line 380 of file connection.hpp.

## set_write_handler()

template<typename config>

void websocketpp::transport::iostream::connection< config >::set_write_handler | ( | write_handler | h | ) |

inline

Sets the write handler.

The write handler is called when the iostream transport receives data that needs to be written to the appropriate output location. This handler can be used in place of registering an ostream for output.

The signature of the handler is lib::error_code (connection_hdl, char const *, size_t) The code returned will be reported and logged by the core library.

See also, set_vector_write_handler, for an optional write handler that allows more efficient handling of multiple writes at once.

See also
  set_vector_write_handler

Since
  0.5.0

Parameters

  h | The handler to call when data is to be written.

Definition at line 350 of file connection.hpp.

## Friends And Related Symbol Documentation

## operator>>

template<typename config>

std::istream & operator>> | ( | std::istream & | in,
|  | type & | t )

friend

Overloaded stream input operator.

Attempts to read input from the given stream into the transport. Bytes will be extracted from the input stream to fulfill any pending reads. Input in this manner will only read until the current read buffer has been filled. Then it will signal the library to process the input. If the library's input handler adds a new async_read, additional bytes will be read, otherwise the input operation will end.

When this function returns one of the following conditions is true:

- There is no outstanding read operation
- There are no more bytes available in the input stream

You can use tellg() on the input stream to determine if all of the input bytes were read or not.

If there is no pending read operation when the input method is called, it will return immediately and tellg() will not have changed.

Definition at line 142 of file connection.hpp.

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

- websocketpp/transport/iostream/connection.hpp