NetServices: Introduce BHttpRequestStream and abstract interface.

This supports asynchronous transfers of Http Requests to a network
interface.

Change-Id: I845fb2e08160d219f85b7a08d2d8872ac7359b47

docs/user/netservices/HttpStream.dox

@@ -0,0 +1,158 @@
+
+/*
+ * Copyright 2022 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Niels Sascha Reedijk, [email protected]
+ *
+ * Corresponds to:
+ *		headers/private/netservices2/HttpStream.h			hrev?????
+ *		src/kits/network/libnetservices2/HttpStream.cpp		hrev?????
+ */
+
+
+#if __cplusplus >= 201703L
+
+
+/*!
+	\file HttpStream.h
+	\ingroup netservices
+	\brief Provides classes and tools to stream HTTP requests and responses.
+
+	\since Haiku R1
+*/
+
+
+namespace BPrivate {
+
+namespace Network {
+
+
+/*!
+	\class BAbstractDataStream
+	\ingroup netservices
+	\brief Abstract interface for adaptors that incrementally streams HTTP requests or responses.
+
+	While this interface, and the adapters that implement it, are part of the public API, it will
+	be unnecessary for most intents and purposes to use them in your application. They are used
+	internally, by the session classes like \ref BHttpSession.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\struct BAbstractDataStream::TransferInfo
+	\ingroup netservices
+	\brief Data type to describe the progress of a transfer in a stream.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var bool BAbstractDataStream::TransferInfo::complete
+	\brief Set to \c true if the data transmission is complete, or \c false if there is more to be
+		transferred.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var off_t BAbstractDataStream::TransferInfo::currentBytesWritten
+	\brief Set to the number of bytes that was written or read in the most recent call of the
+		\ref BAbstractDataStream::Transfer() call.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var off_t BAbstractDataStream::TransferInfo::totalBytesWritten
+	\brief Set to the total number of bytes that was written or read in all the calls of the
+		\ref BAbstractDataStream::Transfer() method.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var off_t BAbstractDataStream::TransferInfo::totalSize
+	\brief Set to the total number of bytes that will be written or read as part of this
+		stream. It may be set to \c -1 if this is unknown.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn virtual TransferInfo BAbstractDataStream::Transfer(BDataIO *)=0
+	\brief Transfer the next set of bytes to and from the data stream.
+
+	Implementations of this interface should provide this method. It should send or receive from
+	the \ref BDataIO argument interface. When implementing this method, consider that it will be
+	used in asynchronous data transfers. This means:
+		- It should expect the IO's Read/Write calls to return \c B_WOULD_BLOCK. In that case the
+		  data stream will be paused until the next invocation of this method.
+		- The implementation needs to be stateful, so that multiple calls to this method will
+		  incrementally complete the transfer.
+
+	\return The actual progress info of the transfer.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\class BHttpRequestStream
+	\ingroup netservices
+	\brief Stream a \ref BHttpRequest to an IO output.
+
+	\note While this class is part of the public API, it will be unnecessary for most intents and
+		purposes to use them in your application. They are used internally by \ref BHttpSession.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BPrivate::Network::BHttpRequestStream::BHttpRequestStream(const BHttpRequest &request)
+	\brief Constructor
+
+	The lifetime of the object is bound to the lifetime of the \a request object. While the
+	request is being streamed, the \a request object should not be altered, as this may lead to
+	an invalid request being streamed to the network.
+
+	\param request The BHttpRequest to stream.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpRequestStream::~BHttpRequestStream()
+	\brief Destructor
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn virtual TransferInfo BHttpRequestStream::Transfer(BDataIO *target) override
+	\brief Stream the HTTP request to the \a target.
+
+	\param target The IO object to transfer the request to.
+
+	\return The actual progress info of the transfer.
+
+	\since Haiku R1
+*/
+
+
+} // namespace Network
+
+} // namespace BPrivate
+
+#endif