]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com) | |
3 | // | |
4 | // Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | // | |
7 | ||
8 | #ifndef BEAST_HTTP_WRITE_HPP | |
9 | #define BEAST_HTTP_WRITE_HPP | |
10 | ||
11 | #include <beast/config.hpp> | |
12 | #include <beast/http/message.hpp> | |
13 | #include <beast/core/error.hpp> | |
14 | #include <beast/core/async_completion.hpp> | |
15 | #include <ostream> | |
16 | #include <type_traits> | |
17 | ||
18 | namespace beast { | |
19 | namespace http { | |
20 | ||
21 | /** Write a HTTP/1 header to a stream. | |
22 | ||
23 | This function is used to synchronously write a header to | |
24 | a stream. The call will block until one of the following | |
25 | conditions is true: | |
26 | ||
27 | @li The entire header is written. | |
28 | ||
29 | @li An error occurs. | |
30 | ||
31 | This operation is implemented in terms of one or more calls | |
32 | to the stream's `write_some` function. | |
33 | ||
34 | Regardless of the semantic meaning of the header (for example, | |
35 | specifying "Content-Length: 0" and "Connection: close"), | |
36 | this function will not return `boost::asio::error::eof`. | |
37 | ||
38 | @param stream The stream to which the data is to be written. | |
39 | The type must support the @b `SyncWriteStream` concept. | |
40 | ||
41 | @param msg The header to write. | |
42 | ||
43 | @throws system_error Thrown on failure. | |
44 | */ | |
45 | template<class SyncWriteStream, | |
46 | bool isRequest, class Fields> | |
47 | void | |
48 | write(SyncWriteStream& stream, | |
49 | header<isRequest, Fields> const& msg); | |
50 | ||
51 | /** Write a HTTP/1 header to a stream. | |
52 | ||
53 | This function is used to synchronously write a header to | |
54 | a stream. The call will block until one of the following | |
55 | conditions is true: | |
56 | ||
57 | @li The entire header is written. | |
58 | ||
59 | @li An error occurs. | |
60 | ||
61 | This operation is implemented in terms of one or more calls | |
62 | to the stream's `write_some` function. | |
63 | ||
64 | Regardless of the semantic meaning of the header (for example, | |
65 | specifying "Content-Length: 0" and "Connection: close"), | |
66 | this function will not return `boost::asio::error::eof`. | |
67 | ||
68 | @param stream The stream to which the data is to be written. | |
69 | The type must support the @b `SyncWriteStream` concept. | |
70 | ||
71 | @param msg The header to write. | |
72 | ||
73 | @param ec Set to the error, if any occurred. | |
74 | */ | |
75 | template<class SyncWriteStream, | |
76 | bool isRequest, class Fields> | |
77 | void | |
78 | write(SyncWriteStream& stream, | |
79 | header<isRequest, Fields> const& msg, | |
80 | error_code& ec); | |
81 | ||
82 | /** Write a HTTP/1 header asynchronously to a stream. | |
83 | ||
84 | This function is used to asynchronously write a header to | |
85 | a stream. The function call always returns immediately. The | |
86 | asynchronous operation will continue until one of the following | |
87 | conditions is true: | |
88 | ||
89 | @li The entire header is written. | |
90 | ||
91 | @li An error occurs. | |
92 | ||
93 | This operation is implemented in terms of one or more calls to | |
94 | the stream's `async_write_some` functions, and is known as a | |
95 | <em>composed operation</em>. The program must ensure that the | |
96 | stream performs no other write operations until this operation | |
97 | completes. | |
98 | ||
99 | Regardless of the semantic meaning of the header (for example, | |
100 | specifying "Content-Length: 0" and "Connection: close"), | |
101 | this function will not return `boost::asio::error::eof`. | |
102 | ||
103 | @param stream The stream to which the data is to be written. | |
104 | The type must support the @b `AsyncWriteStream` concept. | |
105 | ||
106 | @param msg The header to write. The object must remain valid | |
107 | at least until the completion handler is called; ownership is | |
108 | not transferred. | |
109 | ||
110 | @param handler The handler to be called when the operation | |
111 | completes. Copies will be made of the handler as required. | |
112 | The equivalent function signature of the handler must be: | |
113 | @code void handler( | |
114 | error_code const& error // result of operation | |
115 | ); @endcode | |
116 | Regardless of whether the asynchronous operation completes | |
117 | immediately or not, the handler will not be invoked from within | |
118 | this function. Invocation of the handler will be performed in a | |
119 | manner equivalent to using `boost::asio::io_service::post`. | |
120 | */ | |
121 | template<class AsyncWriteStream, | |
122 | bool isRequest, class Fields, | |
123 | class WriteHandler> | |
124 | #if BEAST_DOXYGEN | |
125 | void_or_deduced | |
126 | #else | |
127 | typename async_completion< | |
128 | WriteHandler, void(error_code)>::result_type | |
129 | #endif | |
130 | async_write(AsyncWriteStream& stream, | |
131 | header<isRequest, Fields> const& msg, | |
132 | WriteHandler&& handler); | |
133 | ||
134 | //------------------------------------------------------------------------------ | |
135 | ||
136 | /** Write a HTTP/1 message to a stream. | |
137 | ||
138 | This function is used to write a message to a stream. The call | |
139 | will block until one of the following conditions is true: | |
140 | ||
141 | @li The entire message is written. | |
142 | ||
143 | @li An error occurs. | |
144 | ||
145 | This operation is implemented in terms of one or more calls | |
146 | to the stream's `write_some` function. | |
147 | ||
148 | The implementation will automatically perform chunk encoding if | |
149 | the contents of the message indicate that chunk encoding is required. | |
150 | If the semantics of the message indicate that the connection should | |
151 | be closed after the message is sent, the error thrown from this | |
152 | function will be `boost::asio::error::eof`. | |
153 | ||
154 | @param stream The stream to which the data is to be written. | |
155 | The type must support the @b `SyncWriteStream` concept. | |
156 | ||
157 | @param msg The message to write. | |
158 | ||
159 | @throws system_error Thrown on failure. | |
160 | */ | |
161 | template<class SyncWriteStream, | |
162 | bool isRequest, class Body, class Fields> | |
163 | void | |
164 | write(SyncWriteStream& stream, | |
165 | message<isRequest, Body, Fields> const& msg); | |
166 | ||
167 | /** Write a HTTP/1 message on a stream. | |
168 | ||
169 | This function is used to write a message to a stream. The call | |
170 | will block until one of the following conditions is true: | |
171 | ||
172 | @li The entire message is written. | |
173 | ||
174 | @li An error occurs. | |
175 | ||
176 | This operation is implemented in terms of one or more calls | |
177 | to the stream's `write_some` function. | |
178 | ||
179 | The implementation will automatically perform chunk encoding if | |
180 | the contents of the message indicate that chunk encoding is required. | |
181 | If the semantics of the message indicate that the connection should | |
182 | be closed after the message is sent, the error returned from this | |
183 | function will be `boost::asio::error::eof`. | |
184 | ||
185 | @param stream The stream to which the data is to be written. | |
186 | The type must support the @b `SyncWriteStream` concept. | |
187 | ||
188 | @param msg The message to write. | |
189 | ||
190 | @param ec Set to the error, if any occurred. | |
191 | */ | |
192 | template<class SyncWriteStream, | |
193 | bool isRequest, class Body, class Fields> | |
194 | void | |
195 | write(SyncWriteStream& stream, | |
196 | message<isRequest, Body, Fields> const& msg, | |
197 | error_code& ec); | |
198 | ||
199 | /** Write a HTTP/1 message asynchronously to a stream. | |
200 | ||
201 | This function is used to asynchronously write a message to | |
202 | a stream. The function call always returns immediately. The | |
203 | asynchronous operation will continue until one of the following | |
204 | conditions is true: | |
205 | ||
206 | @li The entire message is written. | |
207 | ||
208 | @li An error occurs. | |
209 | ||
210 | This operation is implemented in terms of one or more calls to | |
211 | the stream's `async_write_some` functions, and is known as a | |
212 | <em>composed operation</em>. The program must ensure that the | |
213 | stream performs no other write operations until this operation | |
214 | completes. | |
215 | ||
216 | The implementation will automatically perform chunk encoding if | |
217 | the contents of the message indicate that chunk encoding is required. | |
218 | If the semantics of the message indicate that the connection should | |
219 | be closed after the message is sent, the operation will complete with | |
220 | the error set to `boost::asio::error::eof`. | |
221 | ||
222 | @param stream The stream to which the data is to be written. | |
223 | The type must support the @b `AsyncWriteStream` concept. | |
224 | ||
225 | @param msg The message to write. The object must remain valid | |
226 | at least until the completion handler is called; ownership is | |
227 | not transferred. | |
228 | ||
229 | @param handler The handler to be called when the operation | |
230 | completes. Copies will be made of the handler as required. | |
231 | The equivalent function signature of the handler must be: | |
232 | @code void handler( | |
233 | error_code const& error // result of operation | |
234 | ); @endcode | |
235 | Regardless of whether the asynchronous operation completes | |
236 | immediately or not, the handler will not be invoked from within | |
237 | this function. Invocation of the handler will be performed in a | |
238 | manner equivalent to using `boost::asio::io_service::post`. | |
239 | */ | |
240 | template<class AsyncWriteStream, | |
241 | bool isRequest, class Body, class Fields, | |
242 | class WriteHandler> | |
243 | #if BEAST_DOXYGEN | |
244 | void_or_deduced | |
245 | #else | |
246 | typename async_completion< | |
247 | WriteHandler, void(error_code)>::result_type | |
248 | #endif | |
249 | async_write(AsyncWriteStream& stream, | |
250 | message<isRequest, Body, Fields> const& msg, | |
251 | WriteHandler&& handler); | |
252 | ||
253 | //------------------------------------------------------------------------------ | |
254 | ||
255 | /** Serialize a HTTP/1 header to a `std::ostream`. | |
256 | ||
257 | The function converts the header to its HTTP/1 serialized | |
258 | representation and stores the result in the output stream. | |
259 | ||
260 | @param os The output stream to write to. | |
261 | ||
262 | @param msg The message fields to write. | |
263 | */ | |
264 | template<bool isRequest, class Fields> | |
265 | std::ostream& | |
266 | operator<<(std::ostream& os, | |
267 | header<isRequest, Fields> const& msg); | |
268 | ||
269 | /** Serialize a HTTP/1 message to a `std::ostream`. | |
270 | ||
271 | The function converts the message to its HTTP/1 serialized | |
272 | representation and stores the result in the output stream. | |
273 | ||
274 | The implementation will automatically perform chunk encoding if | |
275 | the contents of the message indicate that chunk encoding is required. | |
276 | ||
277 | @param os The output stream to write to. | |
278 | ||
279 | @param msg The message to write. | |
280 | */ | |
281 | template<bool isRequest, class Body, class Fields> | |
282 | std::ostream& | |
283 | operator<<(std::ostream& os, | |
284 | message<isRequest, Body, Fields> const& msg); | |
285 | ||
286 | } // http | |
287 | } // beast | |
288 | ||
289 | #include <beast/http/impl/write.ipp> | |
290 | ||
291 | #endif |