diff --git a/websocketpp/transport/iostream/connection.hpp b/websocketpp/transport/iostream/connection.hpp index 26bd8fd466..4079cf685c 100644 --- a/websocketpp/transport/iostream/connection.hpp +++ b/websocketpp/transport/iostream/connection.hpp @@ -71,12 +71,38 @@ public: m_alog.write(log::alevel::devel,"iostream con transport constructor"); } + /// 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. + * + * @param o A pointer to the ostream to use for output. + */ void register_ostream(std::ostream* o) { // TODO: lock transport state? scoped_lock_type lock(m_read_mutex); m_output_stream = o; } + /// Overloaded stream input operator + /** + * Attempts to read input from the given stream into the transport. Bytes + * will be extracted from the input stream to fullfill 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 avaliable 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. + */ friend std::istream& operator>> (std::istream &in, type &t) { // this serializes calls to external read. scoped_lock_type lock(t.m_read_mutex); @@ -86,6 +112,16 @@ public: return in; } + /// 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. + * + * TODO: allow user settable is_secure flag if this seems useful + * + * @return Whether or not the underlying transport is secure + */ bool is_secure() const { return false; } @@ -109,13 +145,32 @@ protected: callback(lib::error_code()); } - // post? - - - /// read at least num_bytes bytes into buf and then call handler. + /// 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. * - * + * @param num_bytes Don't call handler until at least this many bytes have + * been read. + * + * @param buf The buffer to read bytes into + * + * @param len The size of buf. At maximum, this many bytes will be read. + * + * @param handler The callback to invoke when the operation is complete or + * ends in an error */ void async_read_at_least(size_t num_bytes, char *buf, size_t len, read_handler handler) @@ -147,6 +202,20 @@ protected: m_reading = true; } + /// Asyncronous Transport Write + /** + * Write len bytes in buf to the output stream. 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 + * + * @param buf buffer to read bytes from + * @param len number of bytes to write + * @param handler Callback to invoke with operation status. + */ void async_write(const char* buf, size_t len, write_handler handler) { m_alog.write(log::alevel::devel,"iostream_con async_write"); // TODO: lock transport state? @@ -165,10 +234,19 @@ protected: } } - /// Write - /** - * TODO: unit tests - */ + /// Asyncronous Transport Write (scatter-gather) + /** + * Write a sequence of buffers to the output stream. 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 + * + * @param bufs vector of buffers to write + * @param handler Callback to invoke with operation status. + */ void async_write(const std::vector& bufs, write_handler handler) { m_alog.write(log::alevel::devel,"iostream_con async_write buffer list"); // TODO: lock transport state? @@ -197,7 +275,18 @@ protected: void set_handle(connection_hdl hdl) { m_connection_hdl = hdl; } - + + /// 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. + * + * @param handler The callback to invoke + * + * @return Whether or not the transport was able to register the handler for + * callback. + */ lib::error_code dispatch(dispatch_handler handler) { handler(); return lib::error_code();