binary, text are members of stream (API Change):

fix #446

* message_type is removed

Actions Required:

* Change call sites which use message_type with set_option
  to call stream::binary or stream::text instead.

CHANGELOG.md

@@ -3,12 +3,16 @@ Version 52:
 API Changes:
 
 * auto_fragment is a member of stream
+* binary, text are members of stream
 
 Actions Required:
 
 * Change call sites which use auto_fragment with set_option
   to call stream::auto_fragment instead.
 
+* Change call sites which use message_type with set_option
+  to call stream::binary or stream::text instead.
+
 --------------------------------------------------------------------------------
 
 Version 51

doc/quickref.xml

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

examples/websocket_async_echo_server.hpp

@@ -230,8 +230,7 @@ private:
                     return fail("async_read", ec);
                 // write message
                 d.state = 1;
-                d.ws.set_option(
+                d.ws.binary(d.op == beast::websocket::opcode::binary);
-                    beast::websocket::message_type(d.op));
                 d.ws.async_write(d.db.data(),
                     d.strand.wrap(std::move(*this)));
                 return;

examples/websocket_sync_echo_server.hpp

@@ -215,7 +215,7 @@ private:
                 auto const s = ec.message();
                 break;
             }
-            ws.set_option(beast::websocket::message_type{op});
+            ws.binary(op == beast::websocket::opcode::binary);
             ws.write(b.data(), ec);
             if(ec)
                 break;

include/beast/websocket/option.hpp

@@ -22,45 +22,6 @@
 namespace beast {
 namespace websocket {
 
-/** Message type option.
-
-    This controls the opcode set for outgoing messages. Valid
-    choices are opcode::binary or opcode::text. The setting is
-    only applied at the start when a caller begins a new message.
-    Changing the opcode after a message is started will only
-    take effect after the current message being sent is complete.
-
-    The default setting is opcode::text.
-
-    @note Objects of this type are used with
-          @ref beast::websocket::stream::set_option.
-
-    @par Example
-    Setting the message type to binary.
-    @code
-    ...
-    websocket::stream<ip::tcp::socket> ws(ios);
-    ws.set_option(message_type{opcode::binary});
-    @endcode
-*/
-#if BEAST_DOXYGEN
-using message_type = implementation_defined;
-#else
-struct message_type
-{
-    opcode value;
-
-    explicit
-    message_type(opcode op)
-    {
-        if(op != opcode::binary && op != opcode::text)
-            BOOST_THROW_EXCEPTION(std::invalid_argument{
-                "bad opcode"});
-        value = op;
-    }
-};
-#endif
-
 namespace detail {
 
 using ping_cb = std::function<void(bool, ping_data const&)>;

include/beast/websocket/stream.hpp

@@ -151,111 +151,6 @@ public:
     */
     ~stream() = default;
 
-    /** Set the automatic fragmentation option.
-
-        Determines if outgoing message payloads are broken up into
-        multiple pieces.
-
-        When the automatic fragmentation size is turned on, outgoing
-        message payloads are broken up into multiple frames no larger
-        than the write buffer size.
-
-        The default setting is to fragment messages.
-
-        @note Objects of this type are used with
-              @ref beast::websocket::stream::set_option.
-
-        @par Example
-        Setting the automatic fragmentation option:
-        @code
-        ...
-        websocket::stream<ip::tcp::socket> stream{ios};
-        stream.auto_fragment(true);
-        @endcode
-    */
-    void
-    auto_fragment(bool v)
-    {
-        wr_autofrag_ = v;
-    }
-
-    /// Returns `true` if the automatic fragmentation option is set.
-    bool
-    auto_fragment() const
-    {
-        return wr_autofrag_;
-    }
-
-    /** Set options on the stream.
-
-        The application must ensure that calls to set options
-        are performed within the same implicit or explicit strand.
-
-        @param args One or more stream options to set.
-    */
-#if BEAST_DOXYGEN
-    template<class... Args>
-    void
-    set_option(Args&&... args)
-#else
-    template<class A1, class A2, class... An>
-    void
-    set_option(A1&& a1, A2&& a2, An&&... an)
-#endif
-    {
-        set_option(std::forward<A1>(a1));
-        set_option(std::forward<A2>(a2),
-            std::forward<An>(an)...);
-    }
-
-    /// Set the outgoing message type
-    void
-    set_option(message_type const& o)
-    {
-        wr_opcode_ = o.value;
-    }
-
-    /// Set the permessage-deflate extension options
-    void
-    set_option(permessage_deflate const& o);
-
-    /// Get the permessage-deflate extension options
-    void
-    get_option(permessage_deflate& o)
-    {
-        o = pmd_opts_;
-    }
-
-    /// Set the ping callback
-    void
-    set_option(ping_callback o)
-    {
-        ping_cb_ = std::move(o.value);
-    }
-
-    /// Set the read buffer size
-    void
-    set_option(read_buffer_size const& o)
-    {
-        rd_buf_size_ = o.value;
-        // VFALCO What was the thinking here?
-        //stream_.capacity(o.value);
-    }
-
-    /// Set the maximum incoming message size allowed
-    void
-    set_option(read_message_max const& o)
-    {
-        rd_msg_max_ = o.value;
-    }
-
-    /// Set the size of the write buffer
-    void
-    set_option(write_buffer_size const& o)
-    {
-        wr_buf_size_ = o.value;
-    }
-
     /** Get the io_service associated with the stream.
 
         This function may be used to obtain the io_service object
@@ -328,6 +223,128 @@ public:
         return stream_.lowest_layer();
     }
 
+    /** Set options on the stream.
+
+        The application must ensure that calls to set options
+        are performed within the same implicit or explicit strand.
+
+        @param args One or more stream options to set.
+    */
+#if BEAST_DOXYGEN
+    template<class... Args>
+    void
+    set_option(Args&&... args)
+#else
+    template<class A1, class A2, class... An>
+    void
+    set_option(A1&& a1, A2&& a2, An&&... an)
+#endif
+    {
+        set_option(std::forward<A1>(a1));
+        set_option(std::forward<A2>(a2),
+            std::forward<An>(an)...);
+    }
+
+    /// Set the permessage-deflate extension options
+    void
+    set_option(permessage_deflate const& o);
+
+    /// Get the permessage-deflate extension options
+    void
+    get_option(permessage_deflate& o)
+    {
+        o = pmd_opts_;
+    }
+
+    /// Set the ping callback
+    void
+    set_option(ping_callback o)
+    {
+        ping_cb_ = std::move(o.value);
+    }
+
+    /// Set the read buffer size
+    void
+    set_option(read_buffer_size const& o)
+    {
+        rd_buf_size_ = o.value;
+        // VFALCO What was the thinking here?
+        //stream_.capacity(o.value);
+    }
+
+    /// Set the maximum incoming message size allowed
+    void
+    set_option(read_message_max const& o)
+    {
+        rd_msg_max_ = o.value;
+    }
+
+    /// Set the size of the write buffer
+    void
+    set_option(write_buffer_size const& o)
+    {
+        wr_buf_size_ = o.value;
+    }
+
+    /** Set the automatic fragmentation option.
+
+        Determines if outgoing message payloads are broken up into
+        multiple pieces.
+
+        When the automatic fragmentation size is turned on, outgoing
+        message payloads are broken up into multiple frames no larger
+        than the write buffer size.
+
+        The default setting is to fragment messages.
+
+        @par Example
+        Setting the automatic fragmentation option:
+        @code
+            ws.auto_fragment(true);
+        @endcode
+    */
+    void
+    auto_fragment(bool v)
+    {
+        wr_autofrag_ = v;
+    }
+
+    /// Returns `true` if the automatic fragmentation option is set.
+    bool
+    auto_fragment() const
+    {
+        return wr_autofrag_;
+    }
+
+    /** Set the binary message option.
+
+        This controls whether or not outgoing message opcodes
+        are set to binary or text. The setting is only applied
+        at the start when a caller begins a new message. Changing
+        the opcode after a message is started will only take effect
+        after the current message being sent is complete.
+
+        The default setting is to send text messages.
+
+        @par Example
+        Setting the message type to binary.
+        @code
+            ws.binary(true);
+        @endcode
+    */
+    void
+    binary(bool v)
+    {
+        wr_opcode_ = v ? opcode::binary : opcode::text;
+    }
+
+    /// Returns `true` if the binary message option is set.
+    bool
+    binary() const
+    {
+        return wr_opcode_ == opcode::binary;
+    }
+
     /** Returns the close reason received from the peer.
 
         This is only valid after a read completes with error::closed.
@@ -2721,7 +2738,7 @@ public:
         This operation is implemented in terms of one or more calls to the
         next layer's `write_some` function.
 
-        The current setting of the @ref message_type option controls
+        The current setting of the @ref binary option controls
         whether the message opcode is set to text or binary. If the
         @ref auto_fragment option is set, the message will be split
         into one or more frames as necessary. The actual payload contents
@@ -2756,7 +2773,7 @@ public:
         This operation is implemented in terms of one or more calls to the
         next layer's `write_some` function.
 
-        The current setting of the @ref message_type option controls
+        The current setting of the @ref binary option controls
         whether the message opcode is set to text or binary. If the
         @ref auto_fragment option is set, the message will be split
         into one or more frames as necessary. The actual payload contents
@@ -2798,7 +2815,7 @@ public:
         stream::async_write, stream::async_write_frame, or
         stream::async_close).
 
-        The current setting of the @ref message_type option controls
+        The current setting of the @ref binary option controls
         whether the message opcode is set to text or binary. If the
         @ref auto_fragment option is set, the message will be split
         into one or more frames as necessary. The actual payload contents
@@ -2851,8 +2868,8 @@ public:
 
         If this is the beginning of a new message, the message opcode
         will be set to text or binary as per the current setting of
-        the @ref message_type option. The actual payload sent
+        the @ref binary option. The actual payload sent may be
-        may be transformed as per the WebSocket protocol settings.
+        transformed as per the WebSocket protocol settings.
 
         @param fin `true` if this is the last frame in the message.
 
@@ -2883,8 +2900,8 @@ public:
 
         If this is the beginning of a new message, the message opcode
         will be set to text or binary as per the current setting of
-        the @ref message_type option. The actual payload sent
+        the @ref binary option. The actual payload sent may be
-        may be transformed as per the WebSocket protocol settings.
+        transformed as per the WebSocket protocol settings.
 
         @param fin `true` if this is the last frame in the message.
 
@@ -2920,8 +2937,8 @@ public:
 
         If this is the beginning of a new message, the message opcode
         will be set to text or binary as per the current setting of
-        the @ref message_type option. The actual payload sent
+        the @ref binary option. The actual payload sent may be
-        may be transformed as per the WebSocket protocol settings.
+        transformed as per the WebSocket protocol settings.
 
         @param fin A bool indicating whether or not the frame is the
         last frame in the corresponding WebSockets message.

test/websocket/doc_snippets.cpp

@@ -154,7 +154,7 @@ boost::asio::ip::tcp::socket sock{ios};
     opcode op;
     ws.read(op, buffer);
 
-    ws.set_option(message_type{op});
+    ws.binary(op == opcode::binary);
     ws.write(buffer.data());
     buffer.consume(buffer.size());
 //]
@@ -171,7 +171,7 @@ boost::asio::ip::tcp::socket sock{ios};
         if(fi.fin)
             break;
     }
-    ws.set_option(message_type{fi.op});
+    ws.binary(fi.op == opcode::binary);
     consuming_buffers<multi_buffer::const_buffers_type> cb{buffer.data()};
     for(;;)
     {

test/websocket/ssl/websocket_async_ssl_echo_server.hpp

@@ -254,8 +254,7 @@ private:
                 if(ec)
                     return fail("async_read", ec);
                 d.state = 3;
-                d.ws.set_option(
+                d.ws.binary(d.op == beast::websocket::opcode::binary);
-                    beast::websocket::message_type(d.op));
                 d.ws.async_write(d.db.data(),
                     d.strand.wrap(std::move(*this)));
                 return;

test/websocket/stream.cpp

@@ -555,7 +555,7 @@ public:
         stream<socket_type> ws(ios_);
         ws.auto_fragment(true);
         ws.set_option(write_buffer_size{2048});
-        ws.set_option(message_type{opcode::text});
+        ws.binary(false);
         ws.set_option(read_buffer_size{8192});
         ws.set_option(read_message_max{1 * 1024 * 1024});
         try
@@ -567,15 +567,6 @@ public:
         {
             pass();
         }
-        try
-        {
-            message_type{opcode::close};
-            fail();
-        }
-        catch(std::exception const&)
-        {
-            pass();
-        }
     }
 
     //--------------------------------------------------------------------------
@@ -1279,7 +1270,7 @@ public:
         ws.handshake("localhost", "/");
 
         // Make remote send a ping frame
-        ws.set_option(message_type(opcode::text));
+        ws.binary(false);
         ws.write(buffer_cat(sbuf("PING"), sbuf("ping")));
 
         std::size_t count = 0;
@@ -1346,7 +1337,7 @@ public:
         ws.handshake("localhost", "/");
 
         // Make remote send a text message with bad utf8.
-        ws.set_option(message_type(opcode::binary));
+        ws.binary(true);
         ws.write(buffer_cat(sbuf("TEXT"),
             cbuf(0x03, 0xea, 0xf0, 0x28, 0x8c, 0xbc)));
         opcode op;
@@ -1415,7 +1406,7 @@ public:
         ws.handshake("localhost", "/");
 
         // Cause close to be received
-        ws.set_option(message_type(opcode::binary));
+        ws.binary(true);
         ws.write(sbuf("CLOSE"));
         opcode op;
         multi_buffer db;
@@ -1481,7 +1472,7 @@ public:
         ws.handshake("localhost", "/");
 
         // Cause close to be received
-        ws.set_option(message_type(opcode::binary));
+        ws.binary(true);
         ws.write(sbuf("CLOSE"));
         opcode op;
         multi_buffer db;
@@ -1656,7 +1647,7 @@ public:
 
                 // send message
                 ws.auto_fragment(false);
-                ws.set_option(message_type(opcode::text));
+                ws.binary(false);
                 c.write(ws, sbuf("Hello"));
                 {
                     // receive echoed message
@@ -1690,7 +1681,7 @@ public:
                         BEAST_EXPECT(payload == "");
                     }});
                 c.ping(ws, "");
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, sbuf("Hello"));
                 {
                     // receive echoed message
@@ -1756,9 +1747,9 @@ public:
                 }
 
                 // cause ping
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, sbuf("PING"));
-                ws.set_option(message_type(opcode::text));
+                ws.binary(false);
                 c.write(ws, sbuf("Hello"));
                 {
                     // receive echoed message
@@ -1770,25 +1761,25 @@ public:
                 }
 
                 // cause close
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, sbuf("CLOSE"));
                 restart(error::closed);
 
                 // send bad utf8
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, buffer_cat(sbuf("TEXT"),
                     cbuf(0x03, 0xea, 0xf0, 0x28, 0x8c, 0xbc)));
                 restart(error::failed);
 
                 // cause bad utf8
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, buffer_cat(sbuf("TEXT"),
                     cbuf(0x03, 0xea, 0xf0, 0x28, 0x8c, 0xbc)));
                 c.write(ws, sbuf("Hello"));
                 restart(error::failed);
 
                 // cause bad close
-                ws.set_option(message_type(opcode::binary));
+                ws.binary(true);
                 c.write(ws, buffer_cat(sbuf("RAW"),
                     cbuf(0x88, 0x02, 0x03, 0xed)));
                 restart(error::failed);

test/websocket/websocket_async_echo_server.hpp

@@ -332,9 +332,7 @@ private:
                 else if(match(d.db, "TEXT"))
                 {
                     d.state = 1;
-                    d.ws.set_option(
+                    d.ws.binary(false);
-                        beast::websocket::message_type{
-                            beast::websocket::opcode::text});
                     d.ws.async_write(
                         d.db.data(), d.strand.wrap(std::move(*this)));
                     return;
@@ -359,8 +357,7 @@ private:
                 }
                 // write message
                 d.state = 1;
-                d.ws.set_option(
+                d.ws.binary(d.op == beast::websocket::opcode::binary);
-                    beast::websocket::message_type(d.op));
                 d.ws.async_write(d.db.data(),
                     d.strand.wrap(std::move(*this)));
                 return;

test/websocket/websocket_sync_echo_server.hpp

@@ -312,7 +312,7 @@ private:
                 auto const s = ec.message();
                 break;
             }
-            ws.set_option(beast::websocket::message_type{op});
+            ws.binary(op == beast::websocket::opcode::binary);
             if(match(b, "RAW"))
             {
                 boost::asio::write(
@@ -320,9 +320,7 @@ private:
             }
             else if(match(b, "TEXT"))
             {
-                ws.set_option(
+                ws.binary(false);
-                    beast::websocket::message_type{
-                        beast::websocket::opcode::text});
                 ws.write(b.data(), ec);
             }
             else if(match(b, "PING"))