192 lines
5.2 KiB
Plaintext
192 lines
5.2 KiB
Plaintext
|
|
/*
|
|
* Copyright 2022 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Niels Sascha Reedijk, niels.reedijk@gmail.com
|
|
*
|
|
* 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
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BAbstractDataStream::BufferData(BDataIO* source, size_t maxSize)
|
|
\brief Internal method to append data to the internal buffer.
|
|
|
|
This is a helper method that reads data from a \a source into the internal \ref fBuffer.
|
|
|
|
The number of bytes depends loaded depends on the following properties:
|
|
- The maximum number of bytes for the fBuffer is set to 65kB. If there already is data in
|
|
the buffer, only additional bytes up to the maximum buffer size are read.
|
|
- If \a maxSize is larger than 65kB, or if \a maxSize plus the current size of the input
|
|
buffer is larger than 65kB, only a maximum of 65kB will be loaded.
|
|
- If the \a source has fewer than \a maxSize bytes, then fewer bytes will be loaded.
|
|
|
|
\param source The data source to read from.
|
|
\param maxSize The maximum size to read from the source.
|
|
|
|
\return The output of the \ref BDataIO::Read() call that is executed on the source. When actual
|
|
data is read, this will be the number of bytes that are read. If it is an error, all errors
|
|
will be returned, except for \c B_INTERRUPTED, as interrupted \ref BDataIO::Read() calls
|
|
are retried. It is up to the calling implementation to do further error handling.
|
|
|
|
\exception std::bad_alloc This exception may be raised if it is impossible to allocate memory.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var std::vector<std::byte> BAbstractDataStream::fBuffer
|
|
\brief Internal buffer that can be used by implementations to buffer data.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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
|