Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kHttpServerRequest.h
Go to the documentation of this file.
1 /**
2 * @file kHttpServerRequest.h
3 * @brief Declares the kHttpServerRequest class.
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_REQUEST_H
11 #define K_API_HTTP_SERVER_REQUEST_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kHttpServerRequest
19 * @extends kObject
20 * @ingroup kApi-Io
21 * @brief Supports HTTP server request parsing.
22 */
23 //typedef kObject kHttpServerRequest; --forward-declared in kApiDef.x.h
24
25 kEndHeader()
26
27 /**
28 * Returns a string representing the HTTP request method (e.g. "GET", "POST").
29 *
30 * @public @memberof kHttpServerRequest
31 * @param request Request object.
32 * @return Method string.
33 */
34 kFx(const kChar*) kHttpServerRequest_Method(kHttpServerRequest request);
35
36 /**
37 * Returns a string representing the HTTP request URI (/resources/page.html).
38 *
39 * The URI can be in absolute URI form (http://www.example.com/index.html) or absolute path form (/index.html).
40 * Use the kHttpServerRequest_UriPath function to access the URI in absolute path form.
41 *
42 * @public @memberof kHttpServerRequest
43 * @param request Request object.
44 * @return URI string.
45 */
46 kFx(const kChar*) kHttpServerRequest_Uri(kHttpServerRequest request);
47
48 /**
49 * Returns a string representing the HTTP request URI in absolute path form (/resources/page.html).
50 *
51 * @public @memberof kHttpServerRequest
52 * @param request Request object.
53 * @return Absolute path URI string.
54 */
55 kFx(const kChar*) kHttpServerRequest_UriPath(kHttpServerRequest request);
56
57 /**
58 * Returns a value representing the HTTP version associated with this request.
59 *
60 * @public @memberof kHttpServerRequest
61 * @param request Request object.
62 * @return Request version.
63 */
64 kFx(kVersion) kHttpServerRequest_Version(kHttpServerRequest request);
65
66 /**
67 * Returns the total count of headers parsed from this request.
68 *
69 * The headers reported by this function can include both leading and trailing headers. However, trailing headers
70 * are only reported after the final segment of a chunk-encoded message is parsed.
71 *
72 * @public @memberof kHttpServerRequest
73 * @param request Request object.
74 * @return Header count.
75 */
76 kFx(kSize) kHttpServerRequest_HeaderCount(kHttpServerRequest request);
77
78 /**
79 * Gets a reference to the first header.
80 *
81 * @public @memberof kHttpServerRequest
82 * @param request Request object.
83 * @return First header, or kNULL).
84 */
85 kFx(kPointer) kHttpServerRequest_FirstHeader(kHttpServerRequest request);
86
87 /**
88 * Given a header reference, gets a reference to the next header.
89 *
90 * @public @memberof kHttpServerRequest
91 * @param request Request object.
92 * @param header Current header.
93 * @return Next header, or kNULL).
94 */
95 kFx(kPointer) kHttpServerRequest_NextHeader(kHttpServerRequest request, kPointer header);
96
97 /**
98 * Gets the field name associated with a header reference.
99 *
100 * HTTP header field names are case-insensitive. To avoid ambiguity, the kHttpServerRequest
101 * class converts all header names to Pascal caps (e.g. "Content-Length").
102 *
103 * @public @memberof kHttpServerRequest
104 * @param request Request object.
105 * @param header Header reference.
106 * @return Header field name.
107 */
108 kFx(const kChar*) kHttpServerRequest_HeaderName(kHttpServerRequest request, kPointer header);
109
110 /**
111 * Gets the field value associated with a header reference.
112 *
113 * @public @memberof kHttpServerRequest
114 * @param request Request object.
115 * @param header Header reference.
116 * @return Header field value.
117 */
118 kFx(const kChar*) kHttpServerRequest_HeaderValue(kHttpServerRequest request, kPointer header);
119
120 /**
121 * Finds the header field value associated with the given header field name, if present.
122 *
123 * @public @memberof kHttpServerRequest
124 * @param request Request object.
125 * @param name Header field name.
126 * @return Header field value, or kNULL.
127 */
128 kFx(const kChar*) kHttpServerRequest_FindHeaderValue(kHttpServerRequest request, const kChar* name);
129
130 /**
131 * Reports whether the request has an associated message body.
132 *
133 * @public @memberof kHttpServerRequest
134 * @param request Request object.
135 * @return kTRUE if a message body is present, kFALSE otherwise.
136 */
137 kFx(kBool) kHttpServerRequest_HasBody(kHttpServerRequest request);
138
139 /**
140 * Reports whether the message body is chunk-encoded.
141 *
142 * @public @memberof kHttpServerRequest
143 * @param request Request object.
144 * @return kTRUE if message body is chunk-encoded; kFALSE otherwise.
145 */
146 kFx(kBool) kHttpServerRequest_IsChunkCoded(kHttpServerRequest request);
147
148 /**
149 * Reports the total message length for a simple (non-chunk-encoded) message.
150 *
151 * @public @memberof kHttpServerRequest
152 * @param request Request object.
153 * @return Message length, in bytes, or -1 if not applicable.
154 */
155 kFx(k64s) kHttpServerRequest_ContentLength(kHttpServerRequest request);
156
157 /**
158 * Begins reading the message body.
159 *
160 * For simple messages, call this function once to receive the total message length and a reference to
161 * a stream object that can be used to read the entire message.
162 *
163 * For chunk-encoded messages, call this function to receive the length of the next chunk and a reference to
164 * a stream object that can be used to read the chunk. Each individual chunk must be read out before this
165 * function can be used to learn about the next chunk. Reading is complete when a length of zero is reported
166 * by this function.
167 *
168 * @public @memberof kHttpServerRequest
169 * @param request Request object.
170 * @param length Receives the amount of data, in bytes, that should be read from the stream.
171 * @param stream Receives a reference to a stream object that should be used to read message content.
172 * @return Operation status.
173 */
174 kFx(kStatus) kHttpServerRequest_BeginRead(kHttpServerRequest request, k64u* length, kStream* stream);
175
176 #include <kApi/Io/kHttpServerRequest.x.h>
177
178 #endif
kHttpServerRequest::kHttpServerRequest_NextHeader
kPointer kHttpServerRequest_NextHeader(kHttpServerRequest request, kPointer header)
Given a header reference, gets a reference to the next header.
kHttpServerRequest::kHttpServerRequest_HeaderValue
const kChar * kHttpServerRequest_HeaderValue(kHttpServerRequest request, kPointer header)
Gets the field value associated with a header reference.
kHttpServerRequest::kHttpServerRequest_IsChunkCoded
kBool kHttpServerRequest_IsChunkCoded(kHttpServerRequest request)
Reports whether the message body is chunk-encoded.
kHttpServerRequest::kHttpServerRequest_UriPath
const kChar * kHttpServerRequest_UriPath(kHttpServerRequest request)
Returns a string representing the HTTP request URI in absolute path form (/resources/page.html).
k64u
Represents a 64-bit unsigned integer.
kPointer
Represents a void pointer.
kHttpServerRequest::kHttpServerRequest_Version
kVersion kHttpServerRequest_Version(kHttpServerRequest request)
Returns a value representing the HTTP version associated with this request.
kHttpServerRequest::kHttpServerRequest_FindHeaderValue
const kChar * kHttpServerRequest_FindHeaderValue(kHttpServerRequest request, const kChar *name)
Finds the header field value associated with the given header field name, if present.
kSize
Represents an unsigned integer that can store a pointer address.
kChar
Represents a single unit (byte) in a UTF-8 character.
kHttpServerRequest::kHttpServerRequest_FirstHeader
kPointer kHttpServerRequest_FirstHeader(kHttpServerRequest request)
Gets a reference to the first header.
kHttpServerRequest::kHttpServerRequest_HasBody
kBool kHttpServerRequest_HasBody(kHttpServerRequest request)
Reports whether the request has an associated message body.
kHttpServerRequest::kHttpServerRequest_Uri
const kChar * kHttpServerRequest_Uri(kHttpServerRequest request)
Returns a string representing the HTTP request URI (/resources/page.html).
kHttpServerRequest::kHttpServerRequest_BeginRead
kStatus kHttpServerRequest_BeginRead(kHttpServerRequest request, k64u *length, kStream *stream)
Begins reading the message body.
kStream
Represents an I/O stream.
kHttpServerRequest::kHttpServerRequest_HeaderName
const kChar * kHttpServerRequest_HeaderName(kHttpServerRequest request, kPointer header)
Gets the field name associated with a header reference.
kHttpServerRequest::kHttpServerRequest_ContentLength
k64s kHttpServerRequest_ContentLength(kHttpServerRequest request)
Reports the total message length for a simple (non-chunk-encoded) message.
k64s
Represents a 64-bit signed integer.
kHttpServerRequest::kHttpServerRequest_HeaderCount
kSize kHttpServerRequest_HeaderCount(kHttpServerRequest request)
Returns the total count of headers parsed from this request.
kNetwork.h
IP networking definitions.
kHttpServerRequest::kHttpServerRequest_Method
const kChar * kHttpServerRequest_Method(kHttpServerRequest request)
Returns a string representing the HTTP request method (e.g.
kVersion
Represents a version number.
kStatus
Represents an enumeration of error codes.
kBool
Represents a boolean value.
kHttpServerRequest
Supports HTTP server request parsing.