Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kHttpServerResponse.h
Go to the documentation of this file.
1 /**
2 * @file kHttpServerResponse.h
3 * @brief Declares the kHttpServerResponse class and related types.
4 *
5 * @internal
6 * Copyright (C) 2013-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_HTTP_SERVER_RESPONSE_H
11 #define K_API_HTTP_SERVER_RESPONSE_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @struct kHttpStatus
19 * @extends kValue
20 * @ingroup kApi-Io
21 * @brief HTTP status code enumeration.
22 */
23 typedef k32s kHttpStatus;
24
25 #define kHTTP_STATUS_CONTINUE (100) ///< Continue.
26 #define kHTTP_STATUS_SWITCHING_PROTOCOLS (101) ///< Switching protocols.
27 #define kHTTP_STATUS_OK (200) ///< OK.
28 #define kHTTP_STATUS_CREATED (201) ///< Created.
29 #define kHTTP_STATUS_ACCEPTED (202) ///< Accepted.
30 #define kHTTP_STATUS_NON_AUTHORITATIVE (203) ///< Non-authoritative information.
31 #define kHTTP_STATUS_NO_CONTENT (204) ///< No content.
32 #define kHTTP_STATUS_RESET_CONTENT (205) ///< Reset content.
33 #define kHTTP_STATUS_PARTIAL_CONTENT (206) ///< Partial content.
34 #define kHTTP_STATUS_MULTIPLE_CHOICES (300) ///< Multiple choices.
35 #define kHTTP_STATUS_MOVED_PERMANENTLY (301) ///< Moved permanently.
36 #define kHTTP_STATUS_FOUND (302) ///< Found.
37 #define kHTTP_STATUS_SEE_OTHER (303) ///< See other.
38 #define kHTTP_STATUS_NOT_MODIFIED (304) ///< Not modified.
39 #define kHTTP_STATUS_USE_PROXY (305) ///< Use proxy.
40 #define kHTTP_STATUS_TEMPORARY_REDIRECT (307) ///< Temporary redirect.
41 #define kHTTP_STATUS_BAD_REQUEST (400) ///< Bad request.
42 #define kHTTP_STATUS_UNAUTHORIZED (401) ///< Unauthorized.
43 #define kHTTP_STATUS_PAYMENT_REQUIRED (402) ///< Payment required.
44 #define kHTTP_STATUS_FORBIDDEN (403) ///< Forbidden.
45 #define kHTTP_STATUS_NOT_FOUND (404) ///< Not found.
46 #define kHTTP_STATUS_METHOD_NOT_ALLOWED (405) ///< Method not allowed.
47 #define kHTTP_STATUS_NOT_ACCEPTABLE (406) ///< Not acceptable.
48 #define kHTTP_STATUS_PROXY_AUTH_REQUIRED (407) ///< Proxy authentication required.
49 #define kHTTP_STATUS_REQUEST_TIMEOUT (408) ///< Request timeout.
50 #define kHTTP_STATUS_CONFLICT (409) ///< Conflict.
51 #define kHTTP_STATUS_GONE (410) ///< Gone.
52 #define kHTTP_STATUS_LENGTH_REQUIRED (411) ///< Length required.
53 #define kHTTP_STATUS_PRECONDITION_FAILED (412) ///< Precondition failed.
54 #define kHTTP_STATUS_REQUEST_ENTITY_SIZE (413) ///< Request entity too large.
55 #define kHTTP_STATUS_REQUEST_URI_SIZE (414) ///< Request URI size too large.
56 #define kHTTP_STATUS_UNSUPPORTED_MEDIA_TYPE (415) ///< Unsupported media type.
57 #define kHTTP_STATUS_INVALID_RANGE (416) ///< Requested range not satisfiable.
58 #define kHTTP_STATUS_EXPECTATION_FAILED (417) ///< Expectation failed.
59 #define kHTTP_STATUS_INTERNAL_SERVER_ERROR (500) ///< Internal server error.
60 #define kHTTP_STATUS_NOT_IMPLEMENTED (501) ///< Not implemented.
61 #define kHTTP_STATUS_BAD_GATEWAY (502) ///< Bad gateway.
62 #define kHTTP_STATUS_SERVICE_UNAVAILABLE (503) ///< Service unavailable.
63 #define kHTTP_STATUS_GATEWAY_TIMEOUT (504) ///< Gateway timeout.
64 #define kHTTP_STATUS_UNSUPPORTED_VERSION (505) ///< HTTP version not supported.
65
66 /**
67 * @class kHttpServerResponse
68 * @extends kObject
69 * @ingroup kApi-Io
70 * @brief Supports HTTP server response formatting.
71 */
72 //typedef kObject kHttpServerResponse; --forward-declared in kApiDef.x.h
73
74 /**
75 * Sets the version associated with this HTTP response.
76 *
77 * By default, version 1.1 is assumed.
78 *
79 * This function can only be called prior to writing the message body.
80 *
81 * @public @memberof kHttpServerResponse
82 * @param response Response object.
83 * @param version Message version.
84 * @return Operation status.
85 */
86 kFx(kStatus) kHttpServerResponse_SetVersion(kHttpServerResponse response, kVersion version);
87
88 /**
89 * Sets the HTTP status code associated with this response.
90 *
91 * By default, status code 200 (OK) is assumed.
92 *
93 * This function can only be called prior to writing the message body.
94 *
95 * @public @memberof kHttpServerResponse
96 * @param response Response object.
97 * @param status HTTP status code.
98 * @return Operation status.
99 */
100 kFx(kStatus) kHttpServerResponse_SetStatus(kHttpServerResponse response, kHttpStatus status);
101
102 /**
103 * Sets the HTTP status description associated with this response.
104 *
105 * If a custom description is not provided, a default description based on the status code will be sent.
106 *
107 * This function can only be called prior to writing the message body.
108 *
109 * @public @memberof kHttpServerResponse
110 * @param response Response object.
111 * @param reason HTTP status description.
112 * @return Operation status.
113 */
114 kFx(kStatus) kHttpServerResponse_SetReason(kHttpServerResponse response, const kChar* reason);
115
116 /**
117 * Instructs the HTTP server to close this connection when message processing is complete.
118 *
119 * This function can only be called prior to writing the message body.
120 *
121 * Use of this function will automatically add the 'connection: closed' header.
122 *
123 * @public @memberof kHttpServerResponse
124 * @param response Response object.
125 * @param closed kTRUE to close the connection; kFALSE otherwise.
126 * @return Operation status.
127 */
128 kFx(kStatus) kHttpServerResponse_SetClosed(kHttpServerResponse response, kBool closed);
129
130 /**
131 * Adds a header value to the response.
132 *
133 * Headers that can be determined from the information provided in other functions (e.g. 'Content-Length',
134 * 'Transfer-Encoding', 'Connection') will be generated automatically and should not normally be provided via this function.
135 *
136 * If multiple headers with the same field name are provided, each subsequent header value will be
137 * added to the previous header values (comma-separated).
138 *
139 * Leading headers should be added prior to writing the message body. Trailing headers can be generated by
140 * calling this function after writing at least one chunk-encoded body segment.
141 *
142 * @public @memberof kHttpServerResponse
143 * @param response Response object.
144 * @param name Header field name.
145 * @param value Header field value.
146 * @return Operation status.
147 */
148 kFx(kStatus) kHttpServerResponse_AddHeader(kHttpServerResponse response, const kChar* name, const kChar* value);
149
150 /**
151 * Sets the value of a header in the response.
152 *
153 * Headers that can be determined from the information provided in other functions (e.g. 'Content-Length',
154 * 'Transfer-Encoding', 'Connection') will be generated automatically and should not normally be provided via this function.
155 *
156 * Leading headers should be added prior to writing the message body. Trailing headers can be generated by
157 * calling this function after writing at least one chunk-encoded body segment.
158 *
159 * @public @memberof kHttpServerResponse
160 * @param response Response object.
161 * @param name Header field name.
162 * @param value Header field value.
163 * @return Operation status.
164 */
165 kFx(kStatus) kHttpServerResponse_SetHeader(kHttpServerResponse response, const kChar* name, const kChar* value);
166
167 /**
168 * Begins writing a simple message body.
169 *
170 * Use the stream provided by this function to write the message body.
171 *
172 * Use of this function will automatically add the 'Content-Length' header.
173 *
174 * @public @memberof kHttpServerResponse
175 * @param response Response object.
176 * @param length Total length of the message body, in bytes.
177 * @param stream Receives a reference to a stream object that should be used to write the message body.
178 * @return Operation status.
179 */
180 kFx(kStatus) kHttpServerResponse_BeginWriteContent(kHttpServerResponse response, k64u length, kStream* stream);
181
182 /**
183 * Begins writing a chunk-encoded message body segment.
184 *
185 * Use the stream provided by this function to write the message chunk. Call this function with a length
186 * of zero to signify that writing is complete.
187 *
188 * Use of this function will automatically add the 'Transfer-Encoding: chunked' header.
189 *
190 * @public @memberof kHttpServerResponse
191 * @param response Response object.
192 * @param length Length of the message chunk, in bytes.
193 * @param stream Receives a reference to a stream object that should be used to write the message chunk.
194 * @return Operation status.
195 */
196 kFx(kStatus) kHttpServerResponse_BeginWriteChunk(kHttpServerResponse response, k64u length, kStream* stream);
197
198 kEndHeader()
199
200 #include <kApi/Io/kHttpServerResponse.x.h>
201
202 #endif
k64u
Represents a 64-bit unsigned integer.
kHttpServerResponse::kHttpServerResponse_SetHeader
kStatus kHttpServerResponse_SetHeader(kHttpServerResponse response, const kChar *name, const kChar *value)
Sets the value of a header in the response.
kChar
Represents a single unit (byte) in a UTF-8 character.
kHttpServerResponse::kHttpServerResponse_BeginWriteContent
kStatus kHttpServerResponse_BeginWriteContent(kHttpServerResponse response, k64u length, kStream *stream)
Begins writing a simple message body.
kHttpServerResponse::kHttpServerResponse_SetClosed
kStatus kHttpServerResponse_SetClosed(kHttpServerResponse response, kBool closed)
Instructs the HTTP server to close this connection when message processing is complete.
kHttpServerResponse::kHttpServerResponse_BeginWriteChunk
kStatus kHttpServerResponse_BeginWriteChunk(kHttpServerResponse response, k64u length, kStream *stream)
Begins writing a chunk-encoded message body segment.
kHttpServerResponse::kHttpServerResponse_SetStatus
kStatus kHttpServerResponse_SetStatus(kHttpServerResponse response, kHttpStatus status)
Sets the HTTP status code associated with this response.
kHttpStatus
HTTP status code enumeration.
kHttpServerResponse::kHttpServerResponse_SetVersion
kStatus kHttpServerResponse_SetVersion(kHttpServerResponse response, kVersion version)
Sets the version associated with this HTTP response.
kStream
Represents an I/O stream.
k32s
Represents a 32-bit signed integer.
kHttpServerResponse
Supports HTTP server response formatting.
kNetwork.h
IP networking definitions.
kVersion
Represents a version number.
kStatus
Represents an enumeration of error codes.
kHttpServerResponse::kHttpServerResponse_SetReason
kStatus kHttpServerResponse_SetReason(kHttpServerResponse response, const kChar *reason)
Sets the HTTP status description associated with this response.
kHttpServerResponse::kHttpServerResponse_AddHeader
kStatus kHttpServerResponse_AddHeader(kHttpServerResponse response, const kChar *name, const kChar *value)
Adds a header value to the response.
kBool
Represents a boolean value.