chore(WebSocket): docs

Net/include/Poco/Net/WebSocket.h

@@ -49,6 +49,11 @@ class Net_API WebSocket: public StreamSocket
 	/// Note that special frames like PING must be handled at
 	/// application level. In the case of a PING, a PONG message
 	/// must be returned.
+	///
+	/// Once connected, a WebSocket can be put into non-blocking
+	/// mode, by calling setBlocking(false). 
+	/// Please refer to the sendFrame() and receiveFrame() documentation
+	/// for non-blocking behavior.
 {
 public:
 	enum Mode
@@ -244,11 +249,15 @@ class Net_API WebSocket: public StreamSocket
 		/// Values from the FrameFlags, FrameOpcodes and SendFlags enumerations
 		/// can be specified in flags.
 		///
-		/// Returns the number of bytes sent, which may be
-		/// less than the number of bytes specified.
+		/// Returns the number of bytes sent.
 		///
-		/// Certain socket implementations may also return a negative
-		/// value denoting a certain condition.
+		/// If the WebSocket is non-blocking and the frame could not
+		/// be sent in full, returns -1. In this case, the call
+		/// to sendFrame() must be repeated with exactly the same
+		/// parameters as soon as the socket becomes writable again 
+		/// (see select() or poll()). 
+		/// The value of length is returned after the complete
+		/// frame has been sent.
 
 	int receiveFrame(void* buffer, int length, int& flags);
 		/// Receives a frame from the socket and stores it
@@ -278,6 +287,14 @@ class Net_API WebSocket: public StreamSocket
 		///
 		/// The frame flags and opcode (FrameFlags and FrameOpcodes)
 		/// is stored in flags.
+		///
+		/// In case of a non-blocking socket, may return -1, even
+		/// if a partial frame has been received. 
+		/// In this case, receiveFrame() should be called again as 
+		/// soon as more data becomes available (see select() or poll()).
+		/// Eventually, receiveFrame() will return the complete frame.
+		/// The given buffer will not be modified until the full frame has 
+		/// been received.
 
 	int receiveFrame(Poco::Buffer<char>& buffer, int& flags);
 		/// Receives a frame from the socket and stores it
@@ -320,6 +337,14 @@ class Net_API WebSocket: public StreamSocket
 		/// called on the buffer beforehand, if the expectation is that
 		/// the received data is stored starting at the beginning of the
 		/// buffer.
+		///
+		/// In case of a non-blocking socket, may return -1, even
+		/// if a partial frame has been received. 
+		/// In this case, receiveFrame() should be called again as 
+		/// soon as more data becomes available (see select() or poll()).
+		/// Eventually, receiveFrame() will return the complete frame.
+		/// The given buffer will not be modified until the full frame has 
+		/// been received.
 
 	Mode mode() const;
 		/// Returns WS_SERVER if the WebSocket is a server-side

Net/include/Poco/Net/WebSocketImpl.h

@@ -42,12 +42,21 @@ class Net_API WebSocketImpl: public StreamSocketImpl
 	// StreamSocketImpl
 	virtual int sendBytes(const void* buffer, int length, int flags);
 		/// Sends a WebSocket protocol frame.
+		///
+		/// See WebSocket::sendFrame() for more information, including
+		/// behavior if set to non-blocking.
 
 	virtual int receiveBytes(void* buffer, int length, int flags);
 		/// Receives a WebSocket protocol frame.
+		///
+		/// See WebSocket::receiveFrame() for more information, including
+		/// behavior if set to non-blocking.
 
 	virtual int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& span = 0);
 		/// Receives a WebSocket protocol frame.
+		///
+		/// See WebSocket::receiveFrame() for more information, including
+		/// behavior if set to non-blocking.
 
 	virtual SocketImpl* acceptConnection(SocketAddress& clientAddr);
 	virtual void connect(const SocketAddress& address);