boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-07-31 05:17:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Tidy up some WebSocket javadocs

Browse Source
This commit is contained in:
Vinnie Falco
2017-02-07 19:11:24 -05:00
parent a983bb4fe7
commit 5bbbb1fb30
3 changed files with 92 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
include/beast/websocket/detail/stream_base.hpp
View File

@ -66,7 +66,7 @@ protected:
bool wr_close_; // sent close frame
op* wr_block_; // op currenly writing
ping_data* ping_data_; // where to put pong payload
ping_data* ping_data_; // where to put the payload
invokable rd_op_; // invoked after write completes
invokable wr_op_; // invoked after read completes
close_reason cr_; // set from received close frame

15
include/beast/websocket/option.hpp
View File

@ -236,14 +236,15 @@ struct permessage_deflate
/** Ping callback option.
Sets the callback to be invoked whenever a ping or pong is
received during a call to
@ref beast::websocket::stream::read,
@ref beast::websocket::stream::read_frame,
@ref beast::websocket::stream::async_read, or
@ref beast::websocket::stream::async_read_frame.
received during a call to one of the following functions:
Unlike completion handlers, the callback will be invoked for
each received ping and pong pong during a call to any
@li @ref beast::websocket::stream::read
@li @ref beast::websocket::stream::read_frame
@li @ref beast::websocket::stream::async_read
@li @ref beast::websocket::stream::async_read_frame
Unlike completion handlers, the callback will be invoked
for each received ping and pong during a call to any
synchronous or asynchronous read function. The operation is
passive, with no associated error code, and triggered by reads.

136
include/beast/websocket/stream.hpp
View File

@ -1118,12 +1118,17 @@ public:
the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li A pong frame is sent when a ping frame is received.
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
@param op A value to receive the message type.
This object must remain valid until the handler is called.
@ -1153,12 +1158,17 @@ public:
the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li A pong frame is sent when a ping frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
@param op A value to receive the message type.
This object must remain valid until the handler is called.
@ -1193,12 +1203,17 @@ public:
the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li A pong frame is sent when a ping frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
Because of the need to handle control frames, read operations
can cause writes to take place. These writes are managed
@ -1248,19 +1263,24 @@ public:
This call is implemented in terms of one or more calls to the
stream's `read_some` and `write_some` operations.
Upon success, fi is filled out to reflect the message payload
contents. op is set to binary or text, and the fin flag
Upon success, `fi` is filled out to reflect the message payload
contents. `op` is set to binary or text, and the `fin` flag
indicates if all the message data has been read in. To read the
entire message, callers should repeat the read_frame operation
until fi.fin is true. A message with no payload will have
fi.fin == true, and zero bytes placed into the stream buffer.
entire message, callers should keep calling @ref read_frame
until `fi.fin == true`. A message with no payload will have
`fi.fin == true`, and zero bytes placed into the stream buffer.
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li A pong frame is sent when a ping frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
@param fi An object to store metadata about the message.
@ -1286,19 +1306,24 @@ public:
This call is implemented in terms of one or more calls to the
stream's `read_some` and `write_some` operations.
Upon success, fi is filled out to reflect the message payload
contents. op is set to binary or text, and the fin flag
Upon success, `fi` is filled out to reflect the message payload
contents. `op` is set to binary or text, and the `fin` flag
indicates if all the message data has been read in. To read the
entire message, callers should repeat the read_frame operation
until fi.fin is true. A message with no payload will have
fi.fin == true, and zero bytes placed into the stream buffer.
entire message, callers should keep calling @ref read_frame
until `fi.fin == true`. A message with no payload will have
`fi.fin == true`, and zero bytes placed into the stream buffer.
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li A pong frame is sent when a ping frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
@param fi An object to store metadata about the message.
@ -1328,20 +1353,25 @@ public:
ensure that the stream performs no other reads until this operation
completes.
Upon a successful completion, fi is filled out to reflect the
message payload contents. op is set to binary or text, and the
fin flag indicates if all the message data has been read in.
To read the entire message, callers should repeat the
read_frame operation until fi.fin is true. A message with no
payload will have fi.fin == true, and zero bytes placed into
the stream buffer.
Upon a successful completion, `fi` is filled out to reflect the
message payload contents. `op` is set to binary or text, and the
`fin` flag indicates if all the message data has been read in.
To read the entire message, callers should keep calling
@ref read_frame until `fi.fin == true`. A message with no payload
will have `fi.fin == true`, and zero bytes placed into the stream
buffer.
Control frames encountered while reading frame or message data
are handled automatically. Pings are replied to with a pong,
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close
procedure. When a close frame is received, this call will
eventually return @ref error::closed.
During reads, the implementation handles control frames as
follows:
@li The @ref ping_callback is invoked when a ping frame
or pong frame is received.
@li A pong frame is sent when a ping frame is received.
@li The WebSocket close procedure is started if a close frame
is received. In this case, the operation will eventually
complete with the error set to @ref error::closed.
Because of the need to handle control frames, read operations
can cause writes to take place. These writes are managed