boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-01 22:04:34 +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 bool wr_close_; // sent close frame
op* wr_block_; // op currenly writing 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 rd_op_; // invoked after write completes
invokable wr_op_; // invoked after read completes invokable wr_op_; // invoked after read completes
close_reason cr_; // set from received close frame 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. /** Ping callback option.
Sets the callback to be invoked whenever a ping or pong is Sets the callback to be invoked whenever a ping or pong is
received during a call to received during a call to one of the following functions:
@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.
Unlike completion handlers, the callback will be invoked for @li @ref beast::websocket::stream::read
each received ping and pong pong during a call to any @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 synchronous or asynchronous read function. The operation is
passive, with no associated error code, and triggered by reads. 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 the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length). hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li A pong frame is sent when a ping frame is received.
procedure. When a close frame is received, this call will
eventually return @ref error::closed. @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. @param op A value to receive the message type.
This object must remain valid until the handler is called. 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 the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length). hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li The @ref ping_callback is invoked when a ping frame
procedure. When a close frame is received, this call will or pong frame is received.
eventually return @ref error::closed.
@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. @param op A value to receive the message type.
This object must remain valid until the handler is called. 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 the message type, and the input area of the stream buffer will
hold all the message payload bytes (which may be zero in length). hold all the message payload bytes (which may be zero in length).
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li The @ref ping_callback is invoked when a ping frame
procedure. When a close frame is received, this call will or pong frame is received.
eventually return @ref error::closed.
@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 Because of the need to handle control frames, read operations
can cause writes to take place. These writes are managed 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 This call is implemented in terms of one or more calls to the
stream's `read_some` and `write_some` operations. stream's `read_some` and `write_some` operations.
Upon success, fi is filled out to reflect the message payload Upon success, `fi` is filled out to reflect the message payload
contents. op is set to binary or text, and the fin flag 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 indicates if all the message data has been read in. To read the
entire message, callers should repeat the read_frame operation entire message, callers should keep calling @ref read_frame
until fi.fin is true. A message with no payload will have until `fi.fin == true`. A message with no payload will have
fi.fin == true, and zero bytes placed into the stream buffer. `fi.fin == true`, and zero bytes placed into the stream buffer.
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li The @ref ping_callback is invoked when a ping frame
procedure. When a close frame is received, this call will or pong frame is received.
eventually return @ref error::closed.
@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. @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 This call is implemented in terms of one or more calls to the
stream's `read_some` and `write_some` operations. stream's `read_some` and `write_some` operations.
Upon success, fi is filled out to reflect the message payload Upon success, `fi` is filled out to reflect the message payload
contents. op is set to binary or text, and the fin flag 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 indicates if all the message data has been read in. To read the
entire message, callers should repeat the read_frame operation entire message, callers should keep calling @ref read_frame
until fi.fin is true. A message with no payload will have until `fi.fin == true`. A message with no payload will have
fi.fin == true, and zero bytes placed into the stream buffer. `fi.fin == true`, and zero bytes placed into the stream buffer.
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li The @ref ping_callback is invoked when a ping frame
procedure. When a close frame is received, this call will or pong frame is received.
eventually return @ref error::closed.
@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. @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 ensure that the stream performs no other reads until this operation
completes. completes.
Upon a successful completion, fi is filled out to reflect the Upon a successful completion, `fi` is filled out to reflect the
message payload contents. op is set to binary or text, and 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. `fin` flag indicates if all the message data has been read in.
To read the entire message, callers should repeat the To read the entire message, callers should keep calling
read_frame operation until fi.fin is true. A message with no @ref read_frame until `fi.fin == true`. A message with no payload
payload will have fi.fin == true, and zero bytes placed into will have `fi.fin == true`, and zero bytes placed into the stream
the stream buffer. buffer.
Control frames encountered while reading frame or message data During reads, the implementation handles control frames as
are handled automatically. Pings are replied to with a pong, follows:
received pings and pongs invoke the @ref ping_callback if the
option is set, and close frames initiate the WebSocket close @li The @ref ping_callback is invoked when a ping frame
procedure. When a close frame is received, this call will or pong frame is received.
eventually return @ref error::closed.
@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 Because of the need to handle control frames, read operations
can cause writes to take place. These writes are managed can cause writes to take place. These writes are managed