Skip to content

Commit 0807cf5

Browse files
swisspolswisspol
committed
swisspol#33 Documented Requests/ and Responses/
1 parent c6701cd commit 0807cf5

11 files changed

Lines changed: 315 additions & 20 deletions

‎GCDWebServer/Core/GCDWebServerRequest.h‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,12 +126,12 @@
126126
@property(nonatomic, readonly) NSUInteger contentLength;
127127

128128
/**
129-
* Returns the parsed "If-Modified-Since" header or nil if absent of malformed.
129+
* Returns the parsed "If-Modified-Since" header or nil if absent or malformed.
130130
*/
131131
@property(nonatomic, readonly) NSDate* ifModifiedSince;
132132

133133
/**
134-
* Returns the parsed "If-None-Match" header or nil if absent of malformed.
134+
* Returns the parsed "If-None-Match" header or nil if absent or malformed.
135135
*/
136136
@property(nonatomic, readonly) NSString* ifNoneMatch;
137137

‎GCDWebServer/Core/GCDWebServerResponse.h‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@
138138
@property(nonatomic, getter=isGZipContentEncodingEnabled) BOOL gzipContentEncodingEnabled;
139139

140140
/**
141-
* Creates a default response.
141+
* Creates an empty response.
142142
*/
143143
+ (instancetype)response;
144144

@@ -166,7 +166,7 @@
166166
@interface GCDWebServerResponse (Extensions)
167167

168168
/**
169-
* Creates a default response with a specific HTTP status code.
169+
* Creates a empty response with a specific HTTP status code.
170170
*/
171171
+ (instancetype)responseWithStatusCode:(NSInteger)statusCode;
172172

@@ -176,7 +176,7 @@
176176
+ (instancetype)responseWithRedirect:(NSURL*)location permanent:(BOOL)permanent;
177177

178178
/**
179-
* Initializes a default response with a specific HTTP status code.
179+
* Initializes an empty response with a specific HTTP status code.
180180
*/
181181
- (instancetype)initWithStatusCode:(NSInteger)statusCode;
182182

‎GCDWebServer/Requests/GCDWebServerDataRequest.h‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,34 @@
2727

2828
#import "GCDWebServerRequest.h"
2929

30+
/**
31+
* The GCDWebServerDataRequest subclass of GCDWebServerRequest stores the body
32+
* of the HTTP request in memory.
33+
*/
3034
@interface GCDWebServerDataRequest : GCDWebServerRequest
35+
36+
/**
37+
* Returns the data for the request body.
38+
*/
3139
@property(nonatomic, readonly) NSData* data;
40+
3241
@end
3342

3443
@interface GCDWebServerDataRequest (Extensions)
35-
@property(nonatomic, readonly) NSString* text; // Text encoding is extracted from Content-Type or defaults to UTF-8 - Returns nil on error
36-
@property(nonatomic, readonly) id jsonObject; // Returns nil on error
44+
45+
/**
46+
* Returns the data for the request body interpreted as text. If the content
47+
* type of the body is not a text one, or if an error occurs, nil is returned.
48+
*
49+
* The text encoding used to interpret the data is extracted from the
50+
* "Content-Type" header or defaults to UTF-8.
51+
*/
52+
@property(nonatomic, readonly) NSString* text;
53+
54+
/**
55+
* Returns the data for the request body interpreted as a JSON object. If the
56+
* content type of the body is not JSON, or if an error occurs, nil is returned.
57+
*/
58+
@property(nonatomic, readonly) id jsonObject;
59+
3760
@end

‎GCDWebServer/Requests/GCDWebServerFileRequest.h‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,19 @@
2727

2828
#import "GCDWebServerRequest.h"
2929

30+
/**
31+
* The GCDWebServerFileRequest subclass of GCDWebServerRequest stores the body
32+
* of the HTTP request to a file on disk.
33+
*/
3034
@interface GCDWebServerFileRequest : GCDWebServerRequest
35+
36+
/**
37+
* Returns the path to the temporary file containing the request body.
38+
*
39+
* @warning This temporary file will be automatically deleted when the
40+
* GCDWebServerFileRequest is deallocated. If you want to preserve this file,
41+
* you must move it to a different location beforehand.
42+
*/
3143
@property(nonatomic, readonly) NSString* temporaryPath;
44+
3245
@end

‎GCDWebServer/Requests/GCDWebServerMultiPartFormRequest.h‎

Lines changed: 71 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,23 +27,91 @@
2727

2828
#import "GCDWebServerRequest.h"
2929

30+
/**
31+
* The GCDWebServerMultiPart class is an abstract class that wraps the content
32+
* of a part.
33+
*/
3034
@interface GCDWebServerMultiPart : NSObject
31-
@property(nonatomic, readonly) NSString* contentType; // Defaults to "text/plain" per specification if undefined
35+
36+
/**
37+
* Returns the content type retrieved from the part headers or "text/plain"
38+
* if not available (per HTTP specifications).
39+
*/
40+
@property(nonatomic, readonly) NSString* contentType;
41+
42+
/**
43+
* Returns the MIME type component of the content type for the part.
44+
*/
3245
@property(nonatomic, readonly) NSString* mimeType;
46+
3347
@end
3448

49+
/**
50+
* The GCDWebServerMultiPartArgument subclass of GCDWebServerMultiPart wraps
51+
* the content of a part as data in memory.
52+
*/
3553
@interface GCDWebServerMultiPartArgument : GCDWebServerMultiPart
54+
55+
/**
56+
* Returns the data for the part.
57+
*/
3658
@property(nonatomic, readonly) NSData* data;
37-
@property(nonatomic, readonly) NSString* string; // May be nil (only valid for text mime types)
59+
60+
/**
61+
* Returns the data for the part interpreted as text. If the content
62+
* type of the part is not a text one, or if an error occurs, nil is returned.
63+
*
64+
* The text encoding used to interpret the data is extracted from the
65+
* "Content-Type" header or defaults to UTF-8.
66+
*/
67+
@property(nonatomic, readonly) NSString* string;
68+
3869
@end
3970

71+
/**
72+
* The GCDWebServerMultiPartFile subclass of GCDWebServerMultiPart wraps
73+
* the content of a part as a file on disk.
74+
*/
4075
@interface GCDWebServerMultiPartFile : GCDWebServerMultiPart
41-
@property(nonatomic, readonly) NSString* fileName; // May be nil
76+
77+
/**
78+
* Returns the file name retrieved from the part headers.
79+
*/
80+
@property(nonatomic, readonly) NSString* fileName;
81+
82+
/**
83+
* Returns the path to the temporary file containing the part data.
84+
*
85+
* @warning This temporary file will be automatically deleted when the
86+
* GCDWebServerMultiPartFile is deallocated. If you want to preserve this file,
87+
* you must move it to a different location beforehand.
88+
*/
4289
@property(nonatomic, readonly) NSString* temporaryPath;
90+
4391
@end
4492

93+
/**
94+
* The GCDWebServerMultiPartFormRequest subclass of GCDWebServerRequest
95+
* parses the body of the HTTP request as a multipart encoded form.
96+
*/
4597
@interface GCDWebServerMultiPartFormRequest : GCDWebServerRequest
98+
99+
/**
100+
* Returns the argument parts from the multipart encoded form as
101+
* name / GCDWebServerMultiPartArgument pairs.
102+
*/
46103
@property(nonatomic, readonly) NSDictionary* arguments;
104+
105+
/**
106+
* Returns the files parts from the multipart encoded form as
107+
* name / GCDWebServerMultiPartFile pairs.
108+
*/
47109
@property(nonatomic, readonly) NSDictionary* files;
110+
111+
/**
112+
* Returns the MIME type for multipart encoded forms
113+
* i.e. "multipart/form-data".
114+
*/
48115
+ (NSString*)mimeType;
116+
49117
@end

‎GCDWebServer/Requests/GCDWebServerURLEncodedFormRequest.h‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,25 @@
2727

2828
#import "GCDWebServerDataRequest.h"
2929

30+
/**
31+
* The GCDWebServerURLEncodedFormRequest subclass of GCDWebServerRequest
32+
* parses the body of the HTTP request as a URL encoded form using
33+
* GCDWebServerParseURLEncodedForm().
34+
*/
3035
@interface GCDWebServerURLEncodedFormRequest : GCDWebServerDataRequest
31-
@property(nonatomic, readonly) NSDictionary* arguments; // Text encoding is extracted from Content-Type or defaults to UTF-8
36+
37+
/**
38+
* Returns the unescaped names and values for the URL encoded form.
39+
*
40+
* The text encoding used to interpret the data is extracted from the
41+
* "Content-Type" header or defaults to UTF-8.
42+
*/
43+
@property(nonatomic, readonly) NSDictionary* arguments;
44+
45+
/**
46+
* Returns the MIME type for URL encoded forms
47+
* i.e. "application/x-www-form-urlencoded".
48+
*/
3249
+ (NSString*)mimeType;
50+
3351
@end

‎GCDWebServer/Responses/GCDWebServerDataResponse.h‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,81 @@
2727

2828
#import "GCDWebServerResponse.h"
2929

30+
/**
31+
* The GCDWebServerDataResponse subclass of GCDWebServerResponse reads the body
32+
* of the HTTP response from memory.
33+
*/
3034
@interface GCDWebServerDataResponse : GCDWebServerResponse
35+
36+
/**
37+
* Creates a response with data in memory and a given content type.
38+
*/
3139
+ (instancetype)responseWithData:(NSData*)data contentType:(NSString*)type;
40+
41+
/**
42+
* This method is the designated initializer for the class.
43+
*/
3244
- (instancetype)initWithData:(NSData*)data contentType:(NSString*)type;
45+
3346
@end
3447

3548
@interface GCDWebServerDataResponse (Extensions)
49+
50+
/**
51+
* Creates a data response from text encoded using UTF-8.
52+
*/
3653
+ (instancetype)responseWithText:(NSString*)text;
54+
55+
/**
56+
* Creates a data response from HTML encoded using UTF-8.
57+
*/
3758
+ (instancetype)responseWithHTML:(NSString*)html;
59+
60+
/**
61+
* Creates a data response from an HTML template encoded using UTF-8.
62+
* See -initWithHTMLTemplate:variables: for details.
63+
*/
3864
+ (instancetype)responseWithHTMLTemplate:(NSString*)path variables:(NSDictionary*)variables;
65+
66+
/**
67+
* Creates a data response from a serialized JSON object and the default
68+
* "application/json" content type.
69+
*/
3970
+ (instancetype)responseWithJSONObject:(id)object;
71+
72+
/**
73+
* Creates a data response from a serialized JSON object and a custom
74+
* content type.
75+
*/
4076
+ (instancetype)responseWithJSONObject:(id)object contentType:(NSString*)type;
77+
78+
/**
79+
* Initializes a data response from text encoded using UTF-8.
80+
*/
4181
- (instancetype)initWithText:(NSString*)text; // Encodes using UTF-8
42-
- (instancetype)initWithHTML:(NSString*)html; // Encodes using UTF-8
43-
- (instancetype)initWithHTMLTemplate:(NSString*)path variables:(NSDictionary*)variables; // Simple template system that replaces all occurences of "%variable%" with corresponding value (encodes using UTF-8)
82+
83+
/**
84+
* Initializes a data response from HTML encoded using UTF-8.
85+
*/
86+
- (instancetype)initWithHTML:(NSString*)html;
87+
88+
/**
89+
* Initializes a data response from an HTML template encoded using UTF-8.
90+
* All occurences of "%variable%" within the HTML template are replaced with
91+
* their corresponding values.
92+
*/
93+
- (instancetype)initWithHTMLTemplate:(NSString*)path variables:(NSDictionary*)variables;
94+
95+
/**
96+
* Initializes a data response from a serialized JSON object and the default
97+
* "application/json" content type.
98+
*/
4499
- (instancetype)initWithJSONObject:(id)object;
100+
101+
/**
102+
* Initializes a data response from a serialized JSON object and a custom
103+
* content type.
104+
*/
45105
- (instancetype)initWithJSONObject:(id)object contentType:(NSString*)type;
106+
46107
@end

‎GCDWebServer/Responses/GCDWebServerErrorResponse.h‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,54 @@
2828
#import "GCDWebServerDataResponse.h"
2929
#import "GCDWebServerHTTPStatusCodes.h"
3030

31-
// Returns responses with an HTML body containing the error message
31+
/**
32+
* The GCDWebServerDataResponse subclass of GCDWebServerDataResponse generates
33+
* an HTML body from an HTTP status code and an error message.
34+
*/
3235
@interface GCDWebServerErrorResponse : GCDWebServerDataResponse
36+
37+
/**
38+
* Creates a client error response with the corresponding HTTP status code.
39+
*/
3340
+ (instancetype)responseWithClientError:(GCDWebServerClientErrorHTTPStatusCode)errorCode message:(NSString*)format, ... NS_FORMAT_FUNCTION(2,3);
41+
42+
/**
43+
* Creates a server error response with the corresponding HTTP status code.
44+
*/
3445
+ (instancetype)responseWithServerError:(GCDWebServerServerErrorHTTPStatusCode)errorCode message:(NSString*)format, ... NS_FORMAT_FUNCTION(2,3);
46+
47+
/**
48+
* Creates a client error response with the corresponding HTTP status code
49+
* and an optional underlying NSError.
50+
*/
3551
+ (instancetype)responseWithClientError:(GCDWebServerClientErrorHTTPStatusCode)errorCode underlyingError:(NSError*)underlyingError message:(NSString*)format, ... NS_FORMAT_FUNCTION(3,4);
52+
53+
/**
54+
* Creates a server error response with the corresponding HTTP status code
55+
* and an optional underlying NSError.
56+
*/
3657
+ (instancetype)responseWithServerError:(GCDWebServerServerErrorHTTPStatusCode)errorCode underlyingError:(NSError*)underlyingError message:(NSString*)format, ... NS_FORMAT_FUNCTION(3,4);
58+
59+
/**
60+
* Initializes a client error response with the corresponding HTTP status code.
61+
*/
3762
- (instancetype)initWithClientError:(GCDWebServerClientErrorHTTPStatusCode)errorCode message:(NSString*)format, ... NS_FORMAT_FUNCTION(2,3);
63+
64+
/**
65+
* Initializes a server error response with the corresponding HTTP status code.
66+
*/
3867
- (instancetype)initWithServerError:(GCDWebServerServerErrorHTTPStatusCode)errorCode message:(NSString*)format, ... NS_FORMAT_FUNCTION(2,3);
68+
69+
/**
70+
* Initializes a client error response with the corresponding HTTP status code
71+
* and an optional underlying NSError.
72+
*/
3973
- (instancetype)initWithClientError:(GCDWebServerClientErrorHTTPStatusCode)errorCode underlyingError:(NSError*)underlyingError message:(NSString*)format, ... NS_FORMAT_FUNCTION(3,4);
74+
75+
/**
76+
* Initializes a server error response with the corresponding HTTP status code
77+
* and an optional underlying NSError.
78+
*/
4079
- (instancetype)initWithServerError:(GCDWebServerServerErrorHTTPStatusCode)errorCode underlyingError:(NSError*)underlyingError message:(NSString*)format, ... NS_FORMAT_FUNCTION(3,4);
80+
4181
@end

0 commit comments

Comments
 (0)