#include <Pt/Http/Stream.h>
One HTTP stream on a connection. More...
Inherits Connectable, and NonCopyable.
Public Member Functions | |
| ~Stream () | |
| Calls close(). | |
| bool | isValid () const |
| Returns true when the connection still owns this stream. | |
| Channel * | channel () const |
| Returns the bound channel, or null. | |
| const std::string & | protocol () const |
| Returns the Upgrade header value. | |
| void | close () |
| Ends this stream. | |
| std::streambuf * | buffer () |
| Returns the stream buffer of the connection. | |
| void | beginInput () |
| Begins a read into the stream buffer. | |
| std::size_t | endInput () |
| Completes the read started by beginInput(). | |
| void | beginOutput () |
| Begins a write of the bytes buffered in buffer(). | |
| std::size_t | endOutput () |
| Completes the write started by beginOutput(). | |
| void | cancel () |
| Cancels a pending transfer of this stream. | |
| void | setTimeout (std::size_t ms) |
| Sets the stream timeout in milliseconds. | |
| System::EventLoop * | loop () const |
| Returns the event loop of the owning connection. | |
| Signal & | inputReady () |
| Returns the signal emitted when input is ready. | |
| Signal & | outputReady () |
| Returns the signal emitted when output is ready. | |
Stream is one bidirectional channel of a connection the server or the client still owns. A finished reply with status 101 does not hand the TCP connection to the service. The owner keeps that connection and keeps this stream. HTTP/1 has one stream, and it fills the connection. A later multiplexed protocol can issue more than one stream for the same connection.
The connection creates the stream after the 101 reply has been written, and it deletes the stream. This type is not copyable and has no public constructor. The server reports it through Service::onUpgrade(). The client reports it through Client::upgrade(). Both return the stream the owner already holds.
A Channel is the external peer. The stream stores one channel pointer, and the channel stores one stream pointer. Binding that peer accepts the upgrade. A second bind throws std::logic_error. On the server, a stream that still has no channel after onUpgrade() returns is declined, and the server closes it. A WebSocket formats frames into buffer(). The bind is internal to that protocol. Application code uses WebSocket on the client and WebSocketSession on the server.
close() ends this stream. It calls Channel::onDetachStream() when a channel is still bound, and then leaves the connection. That call does not close this stream again and does not emit a protocol signal. While this stream is the only stream of the connection, closing it also closes the connection. The server deletes that connection on its event loop, after the close that requested it has returned. The destructor calls close(). The channel object stays, and its stream pointer is null.
buffer() is the stream buffer of the connection. A channel formats into that buffer and extracts from it. The stream does not take a caller buffer, and it does not expose the socket. beginInput() and beginOutput() start a transfer of that buffer. inputReady() and outputReady() report that a transfer finished, and endInput() and endOutput() complete it. One read and one write may run at a time. cancel() stops the transfer of this stream.
protocol() is the value of the request's Upgrade header. The owner stops the HTTP read and write timeout when it opens the stream. That timeout stays stopped. setTimeout() bounds stream I/O for a channel that sets it.
The example accepts the upgrade by opening a channel on the stream. A service that does not bind a channel declines it.
| ~Stream | ( | ) |
Ends this stream. Closes the connection while this stream is its only stream. Detaches a still-bound channel.
| void close | ( | ) |
Closes the connection while this stream is its only stream. Detaches a still-bound channel without closing this stream again.
| std::size_t endInput | ( | ) |
| System::EventLoop * loop | ( | ) | const |
Returns null after the stream has been closed.