diff --git a/GCDWebServer/Core/GCDWebServer.h b/GCDWebServer/Core/GCDWebServer.h index a4e3199..01084f4 100644 --- a/GCDWebServer/Core/GCDWebServer.h +++ b/GCDWebServer/Core/GCDWebServer.h @@ -59,7 +59,7 @@ typedef GCDWebServerRequest* (^GCDWebServerMatchBlock)(NSString* requestMethod, /** * The GCDWebServerProcessBlock is called after the HTTP request has been fully - * received (i.e. the entire HTTP body has been read). THe block is passed the + * received (i.e. the entire HTTP body has been read). The block is passed the * GCDWebServerRequest created at the previous step by the GCDWebServerMatchBlock. * * The block must return a GCDWebServerResponse or nil on error, which will @@ -102,14 +102,14 @@ extern NSString* const GCDWebServerOption_ServerName; * The authentication method used by the GCDWebServer * (one of "GCDWebServerAuthenticationMethod_..."). * - * The default value is nil i.e. authentication disabled. + * The default value is nil i.e. authentication is disabled. */ extern NSString* const GCDWebServerOption_AuthenticationMethod; /** * The authentication realm used by the GCDWebServer (NSString). * - * The default value is the same as GCDWebServerOption_ServerName. + * The default value is the same as the GCDWebServerOption_ServerName option. */ extern NSString* const GCDWebServerOption_AuthenticationRealm; @@ -125,7 +125,7 @@ extern NSString* const GCDWebServerOption_AuthenticationAccounts; * The class used by the GCDWebServer when instantiating GCDWebServerConnection * (subclass of GCDWebServerConnection). * - * The default value is GCDWebServerConnection class. + * The default value is the GCDWebServerConnection class. */ extern NSString* const GCDWebServerOption_ConnectionClass; @@ -167,7 +167,8 @@ extern NSString* const GCDWebServerOption_AutomaticallySuspendInBackground; /** * HTTP Basic Authentication scheme (see https://tools.ietf.org/html/rfc2617). * - * @warning Use of this method is not recommended as the passwords are sent in clear. + * @warning Use of this authentication scheme is not recommended as the + * passwords are sent in clear. */ extern NSString* const GCDWebServerAuthenticationMethod_Basic; @@ -199,9 +200,11 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; /** * This method is called when the first GCDWebServerConnection is opened by the - * server to serve a series of HTTP requests. A series is ongoing as long as - * new HTTP requests keep coming (and new GCDWebServerConnection instances keep - * being opened), before the last HTTP request has been responded to (and the + * server to serve a series of HTTP requests. + * + * A series of HTTP requests is considered ongoing as long as new HTTP requests + * keep coming (and new GCDWebServerConnection instances keep being opened), + * until before the last HTTP request has been responded to (and the * corresponding last GCDWebServerConnection closed). */ - (void)webServerDidConnect:(GCDWebServer*)server; @@ -226,8 +229,9 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; @end /** - * The GCDWebServer class manages the socket that listens for HTTP requests and - * the list of handlers used to respond to them. + * The GCDWebServer class listens for incoming HTTP requests on a given port, + * then passes each one to a "handler" capable of generating an HTTP response + * for it, which is then sent back to the client. * * See the README.md file for more information about the architecture of GCDWebServer. */ @@ -239,7 +243,7 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; @property(nonatomic, assign) id delegate; /** - * Indicates if the server is currently running. + * Returns YES if the server is currently running. */ @property(nonatomic, readonly, getter=isRunning) BOOL running; @@ -251,7 +255,7 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; @property(nonatomic, readonly) NSUInteger port; /** - * Returns the Bonjour name in used by the server. + * Returns the Bonjour name used by the server. * * @warning This property is only valid if the server is running and Bonjour * registration has successfully completed, which can take up to a few seconds. @@ -265,17 +269,18 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; /** * Adds a handler to the server to handle incoming HTTP requests. - * Handlers are called in a LIFO queue, so the latest added handler overrides - * any previously added ones. * - * @warning Addling handlers while the GCDWebServer is running is not allowed. + * Handlers are called in a LIFO queue, so if multiple handlers can potentially + * respond to a given request, the latest added one wins. + * + * @warning Addling handlers while the server is running is not allowed. */ - (void)addHandlerWithMatchBlock:(GCDWebServerMatchBlock)matchBlock processBlock:(GCDWebServerProcessBlock)processBlock; /** * Removes all handlers previously added to the server. * - * @warning Removing handlers while the GCDWebServer is running is not allowed. + * @warning Removing handlers while the server is running is not allowed. */ - (void)removeAllHandlers; @@ -308,8 +313,8 @@ extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess; * Stops the server and prevents it to accepts new HTTP requests. * * @warning Stopping the server does not abort GCDWebServerConnection instances - * handling already received HTTP requests. These connections will continue to - * execute until the corresponding requests and responses are completed. + * currently handling already received HTTP requests. These connections will + * continue to execute normally until completion. */ - (void)stop; diff --git a/GCDWebServer/Core/GCDWebServerConnection.h b/GCDWebServer/Core/GCDWebServerConnection.h index 7aa75a1..6bdc00c 100644 --- a/GCDWebServer/Core/GCDWebServerConnection.h +++ b/GCDWebServer/Core/GCDWebServerConnection.h @@ -38,8 +38,8 @@ * subclass it to override some hooks. Use the GCDWebServerOption_ConnectionClass * option for GCDWebServer to install your custom subclass. * - * @warning The GCDWebServerConnection retains the GCDWebServer - * until the connection is closed. + * @warning The GCDWebServerConnection retains the GCDWebServer until the + * connection is closed. */ @interface GCDWebServerConnection : NSObject @@ -95,6 +95,7 @@ /** * This method is called when the connection is opened. + * * Return NO to reject the connection e.g. after validating the local * or remote address. */ @@ -103,17 +104,21 @@ /** * This method is called whenever data has been received * from the remote peer (i.e. client). + * + * @warning Do not attempt to modify this data. */ - (void)didReadBytes:(const void*)bytes length:(NSUInteger)length; /** * This method is called whenever data has been sent * to the remote peer (i.e. client). + * + * @warning Do not attempt to modify this data. */ - (void)didWriteBytes:(const void*)bytes length:(NSUInteger)length; /** - * Assuming a valid request was received, this method is called before + * Assuming a valid HTTP request was received, this method is called before * the request is processed. * * Return a non-nil GCDWebServerResponse to bypass the request processing entirely. @@ -124,18 +129,18 @@ - (GCDWebServerResponse*)preflightRequest:(GCDWebServerRequest*)request; /** - * Assuming a valid request was received and -preflightRequest: returned nil, + * Assuming a valid HTTP request was received and -preflightRequest: returned nil, * this method is called to process the request. */ - (GCDWebServerResponse*)processRequest:(GCDWebServerRequest*)request withBlock:(GCDWebServerProcessBlock)block; /** - * Assuming a valid request was received and either -preflightRequest: + * Assuming a valid HTTP request was received and either -preflightRequest: * or -processRequest:withBlock: returned a non-nil GCDWebServerResponse, * this method is called to override the response. * * You can either modify the current response and return it, or return a - * completely different one. + * completely new one. * * The default implementation replaces any response matching the "ETag" or * "Last-Modified-Date" header of the request by a barebone "Not-Modified" (304) @@ -145,7 +150,7 @@ /** * This method is called if any error happens while validing or processing - * the request or no GCDWebServerResponse is generated. + * the request or if no GCDWebServerResponse was generated during processing. * * @warning If the request was invalid (e.g. the HTTP headers were malformed), * the "request" argument will be nil. diff --git a/GCDWebServer/Core/GCDWebServerFunctions.h b/GCDWebServer/Core/GCDWebServerFunctions.h index 201d886..2ef66b2 100644 --- a/GCDWebServer/Core/GCDWebServerFunctions.h +++ b/GCDWebServer/Core/GCDWebServerFunctions.h @@ -50,17 +50,18 @@ NSString* GCDWebServerEscapeURLString(NSString* string); NSString* GCDWebServerUnescapeURLString(NSString* string); /** - * Extracts the unescaped names and values - * from a "application/x-www-form-urlencoded" form. + * Extracts the unescaped names and values from an + * "application/x-www-form-urlencoded" form. * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 */ NSDictionary* GCDWebServerParseURLEncodedForm(NSString* form); /** - * OS X: Returns the IPv4 address as a dotted string of the primary connected - * service or nil if not available. - * iOS: Returns the IPv4 address as a dotted string of the WiFi interface - * if connected or nil otherwise. + * On OS X, returns the IPv4 address as a dotted string of the primary connected + * service or nil if not available. + * + * On iOS, returns the IPv4 address as a dotted string of the WiFi interface + * if connected or nil otherwise. */ NSString* GCDWebServerGetPrimaryIPv4Address(); @@ -76,7 +77,7 @@ NSString* GCDWebServerFormatRFC822(NSDate* date); * https://tools.ietf.org/html/rfc822#section-5 * https://tools.ietf.org/html/rfc1123#section-5.2.14 * - * @warning Timezones are not supported at this time. + * @warning Timezones other than GMT are not supported by this function. */ NSDate* GCDWebServerParseRFC822(NSString* string); @@ -91,7 +92,7 @@ NSString* GCDWebServerFormatISO8601(NSDate* date); * http://tools.ietf.org/html/rfc3339#section-5.6 * * @warning Only "calendar" variant is supported at this time and timezones - * are not supported either. + * other than GMT are not supported either. */ NSDate* GCDWebServerParseISO8601(NSString* string); diff --git a/GCDWebServer/Core/GCDWebServerRequest.h b/GCDWebServer/Core/GCDWebServerRequest.h index 46d9779..b2af74f 100644 --- a/GCDWebServer/Core/GCDWebServerRequest.h +++ b/GCDWebServer/Core/GCDWebServerRequest.h @@ -106,8 +106,8 @@ @property(nonatomic, readonly) NSDictionary* query; /** - * Returns the content type for the body of the request (this property is - * automatically parsed from the HTTP headers). + * Returns the content type for the body of the request parsed from the + * "Content-Type" header. * * This property will be nil if the request has no body or set to * "application/octet-stream" if a body is present but there was no @@ -116,8 +116,8 @@ @property(nonatomic, readonly) NSString* contentType; /** - * Returns the content length for the body of the request (this property is - * automatically parsed from the HTTP headers). + * Returns the content length for the body of the request parsed from the + * "Content-Length" header. * * This property will be set to "NSNotFound" if the request has no body or * if there is a body but no "Content-Length" header, typically because @@ -138,13 +138,13 @@ /** * Returns the parsed "Range" header or (NSNotFound, 0) if absent or malformed. * The range will be set to (offset, length) if expressed from the beginning - * of the body, or (NSNotFound, -length) if expressed from the end of the body. + * of the entity body, or (NSNotFound, -length) if expressed from its end. */ @property(nonatomic, readonly) NSRange byteRange; /** - * Indicates if the client supports gzip content encoding (this property is - * automatically parsed from the HTTP headers). + * Returns YES if the client supports gzip content encoding according to the + * "Accept-Encoding" header. */ @property(nonatomic, readonly) BOOL acceptsGzipContentEncoding; diff --git a/GCDWebServer/Core/GCDWebServerResponse.h b/GCDWebServer/Core/GCDWebServerResponse.h index bbe5686..d65f2f0 100644 --- a/GCDWebServer/Core/GCDWebServerResponse.h +++ b/GCDWebServer/Core/GCDWebServerResponse.h @@ -29,7 +29,7 @@ /** * This protocol is used by the GCDWebServerConnection to communicate with - * the GCDWebServerResponse and read the sent HTTP body data. + * the GCDWebServerResponse and read the HTTP body data to send. * * Note that multiple GCDWebServerBodyReader objects can be chained together * internally e.g. to automatically apply gzip encoding to the content before @@ -48,7 +48,7 @@ - (BOOL)open:(NSError**)error; /** - * This method is called whenever body data is ready to be sent. + * This method is called whenever body data is sent. * * It should return a non-empty NSData if there is body data available, * or an empty NSData there is no more body data, or nil on error and set @@ -67,7 +67,7 @@ * The GCDWebServerResponse class is used to wrap a single HTTP response. * It is instantiated by the handler of the GCDWebServer that handled the request. * If a body is present, the methods from the GCDWebServerBodyReader protocol - * will be called by the GCDWebServerConnection to retrieve it. + * will be called by the GCDWebServerConnection to send it. * * The default implementation of the GCDWebServerBodyReader protocol * on the class simply returns an empty body. @@ -78,16 +78,17 @@ /** * Sets the content type for the body of the response. - * This property must be set if a body is present. * * The default value is nil i.e. the response has no body. + * + * @warning This property must be set if a body is present. */ @property(nonatomic, copy) NSString* contentType; /** * Sets the content length for the body of the response. If a body is present * but this property is set to "NSNotFound", this means the length of the body - * cannot be known ahead of time and chunked transfer encoding will be + * cannot be known ahead of time. Chunked transfer encoding will be * automatically enabled by the GCDWebServerConnection to comply with HTTP/1.1 * specifications. * @@ -152,7 +153,7 @@ * Pass a nil value to remove an additional header. * * @warning Do not attempt to override the primary headers used - * by GCDWebServerResponse e.g. "Content-Type" or "ETag". + * by GCDWebServerResponse like "Content-Type", "ETag", etc... */ - (void)setValue:(NSString*)value forAdditionalHeader:(NSString*)header; diff --git a/GCDWebServer/Responses/GCDWebServerFileResponse.h b/GCDWebServer/Responses/GCDWebServerFileResponse.h index aa1e3f7..391a787 100644 --- a/GCDWebServer/Responses/GCDWebServerFileResponse.h +++ b/GCDWebServer/Responses/GCDWebServerFileResponse.h @@ -30,6 +30,9 @@ /** * The GCDWebServerFileResponse subclass of GCDWebServerResponse reads the body * of the HTTP response from a file on disk. + * + * It will automatically set the lastModifiedDate and eTag properties of the + * GCDWebServerResponse according to the file metadata. */ @interface GCDWebServerFileResponse : GCDWebServerResponse