ping_callback is a member of stream (API Change):

fix #446

* The ping_callback option struct is removed.

Actions Required:

* Change call sites which use ping_callback with set_option to
  call stream::ping_callback instead.

CHANGELOG.md

@@ -7,6 +7,7 @@ API Changes:
 * read_buffer_size is a member of stream
 * read_message_max is a member of stream
 * write_buffer_size is a member of stream
+* ping_callback is a member of stream
 
 Actions Required:
 
@@ -25,6 +26,9 @@ Actions Required:
 * Change call sites which use write_buffer_size with set_option to
   call stream::write_buffer_size instead.
 
+* Change call sites which use ping_callback with set_option to
+  call stream::ping_callback instead.
+
 --------------------------------------------------------------------------------
 
 Version 51

doc/quickref.xml

@@ -124,7 +124,6 @@
           <bridgehead renderas="sect3">Options</bridgehead>
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.websocket__permessage_deflate">permessage_deflate</link></member>
-            <member><link linkend="beast.ref.websocket__ping_callback">ping_callback</link></member>
           </simplelist>
           <bridgehead renderas="sect3">Constants</bridgehead>
           <simplelist type="vert" columns="1">

include/beast/websocket/detail/stream_base.hpp

@@ -46,6 +46,9 @@ struct stream_base
 protected:
     friend class frame_test;
 
+    using ping_callback_type =
+        std::function<void(bool, ping_data const&)>;
+
     struct op {};
 
     detail::maskgen maskgen_;               // source of mask keys
@@ -55,7 +58,7 @@ protected:
     std::size_t wr_buf_size_ = 4096;        // write buffer size
     std::size_t rd_buf_size_ = 4096;        // read buffer size
     opcode wr_opcode_ = opcode::text;       // outgoing message type
-    ping_cb ping_cb_;                       // ping callback
+    ping_callback_type ping_cb_;            // ping callback
     role_type role_;                        // server or client
     bool failed_;                           // the connection failed
 

include/beast/websocket/option.hpp

@@ -22,12 +22,6 @@
 namespace beast {
 namespace websocket {
 
-namespace detail {
-
-using ping_cb = std::function<void(bool, ping_data const&)>;
-
-} // detail
-
 /** permessage-deflate extension options.
 
     These settings control the permessage-deflate extension,
@@ -69,62 +63,6 @@ struct permessage_deflate
     int memLevel = 4;
 };
 
-/** Ping callback option.
-
-    Sets the callback to be invoked whenever a ping or pong is
-    received during a call to one of the following functions:
-
-    @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.
-
-    The signature of the callback must be:
-    @code
-    void
-    callback(
-        bool is_pong,               // `true` if this is a pong
-        ping_data const& payload    // Payload of the pong frame
-    );
-    @endcode
-
-    The value of `is_pong` will be `true` if a pong control frame
-    is received, and `false` if a ping control frame is received.
-
-    If the read operation receiving a ping or pong frame is an
-    asynchronous operation, the callback will be invoked using
-    the same method as that used to invoke the final handler.
-
-    @note Objects of this type are used with
-          @ref beast::websocket::stream::set_option.
-          To remove the ping callback, construct the option with
-          no parameters: `set_option(ping_callback{})`
-*/
-#if BEAST_DOXYGEN
-using ping_callback = implementation_defined;
-#else
-struct ping_callback
-{
-    detail::ping_cb value;
-
-    ping_callback() = default;
-    ping_callback(ping_callback&&) = default;
-    ping_callback(ping_callback const&) = default;
-
-    explicit
-    ping_callback(detail::ping_cb f)
-        : value(std::move(f))
-    {
-    }
-};
-#endif
-
-
 } // websocket
 } // beast
 

include/beast/websocket/stream.hpp

@@ -256,13 +256,6 @@ public:
         o = pmd_opts_;
     }
 
-    /// Set the ping callback
-    void
-    set_option(ping_callback o)
-    {
-        ping_cb_ = std::move(o.value);
-    }
-
     /** Set the automatic fragmentation option.
 
         Determines if outgoing message payloads are broken up into
@@ -327,6 +320,46 @@ public:
         return wr_opcode_ == opcode::binary;
     }
 
+    /** Set the ping callback.
+
+        Sets the callback to be invoked whenever a ping or pong is
+        received during a call to one of the following functions:
+
+        @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.
+
+        The signature of the callback must be:
+        @code
+        void
+        callback(
+            bool is_pong,               // `true` if this is a pong
+            ping_data const& payload    // Payload of the pong frame
+        );
+        @endcode
+
+        The value of `is_pong` will be `true` if a pong control frame
+        is received, and `false` if a ping control frame is received.
+
+        If the read operation receiving a ping or pong frame is an
+        asynchronous operation, the callback will be invoked using
+        the same method as that used to invoke the final handler.
+
+        @param cb The callback to set.
+    */
+    void
+    ping_callback(
+        std::function<void(bool, ping_data const&)> cb)
+    {
+        ping_cb_ = std::move(cb);
+    }
+
     /** Set the read buffer size option.
 
         Sets the size of the read buffer used by the implementation to

test/websocket/doc_snippets.cpp

@@ -193,11 +193,11 @@ boost::asio::ip::tcp::socket sock{ios};
 {
     stream<boost::asio::ip::tcp::socket> ws{ios};
 //[ws_snippet_17
-    ws.set_option(ping_callback(
+    ws.ping_callback(
         [](bool is_pong, ping_data const& payload)
         {
             // Do something with the payload
-        }));
+        });
 //]
 
 //[ws_snippet_18

test/websocket/stream.cpp

@@ -1672,14 +1672,14 @@ public:
 
                 // send ping and message
                 bool pong = false;
-                ws.set_option(ping_callback{
+                ws.ping_callback(
                     [&](bool is_pong, ping_data const& payload)
                     {
                         BEAST_EXPECT(is_pong);
                         BEAST_EXPECT(! pong);
                         pong = true;
                         BEAST_EXPECT(payload == "");
-                    }});
+                    });
                 c.ping(ws, "");
                 ws.binary(true);
                 c.write(ws, sbuf("Hello"));
@@ -1692,15 +1692,15 @@ public:
                     BEAST_EXPECT(op == opcode::binary);
                     BEAST_EXPECT(to_string(db.data()) == "Hello");
                 }
-                ws.set_option(ping_callback{});
+                ws.ping_callback({});
 
                 // send ping and fragmented message
-                ws.set_option(ping_callback{
+                ws.ping_callback(
                     [&](bool is_pong, ping_data const& payload)
                     {
                         BEAST_EXPECT(is_pong);
                         BEAST_EXPECT(payload == "payload");
-                    }});
+                    });
                 ws.ping("payload");
                 c.write_frame(ws, false, sbuf("Hello, "));
                 c.write_frame(ws, false, sbuf(""));
@@ -1713,7 +1713,7 @@ public:
                     BEAST_EXPECT(pong == 1);
                     BEAST_EXPECT(to_string(db.data()) == "Hello, World!");
                 }
-                ws.set_option(ping_callback{});
+                ws.ping_callback({});
 
                 // send pong
                 c.pong(ws, "");