#include <Pt/Http/Stream.h>
One HTTP stream on a connection. More...
Inherits Connectable, and NonCopyable.
Public Member Functions | |
| ~Stream () | |
| Destructor. | |
| bool | isValid () const |
| Returns true when the connection still owns this stream. | |
| StreamSession * | session () const |
| Returns the bound stream session, 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 StreamSession is the external peer. The stream stores one session pointer, and the session 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 session 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 clears the session pointer first and then tells the session that the stream ended, so a close that runs from the session destructor does not re-enter this stream. 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. Destroying the stream tells the session the same way. The session object stays, and its stream pointer is null.
buffer() is the stream buffer of the connection. A session 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. setTimeout() replaces the HTTP read and write timeout for this stream. The owner has already stopped that timeout when it opened the stream.
The example accepts the upgrade by opening a stream session on the stream. A service that does not bind a session declines it.
| ~Stream | ( | ) |
Unbinds the session and notifies it. Does not close the connection. The connection deletes this stream.
| void close | ( | ) |
Closes the connection while this stream is its only stream.
| std::size_t endInput | ( | ) |
| System::EventLoop * loop | ( | ) | const |
Returns null after the stream has been closed.