GCDWebServerRequest.h 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  1. /*
  2. Copyright (c) 2012-2015, Pierre-Olivier Latour
  3. All rights reserved.
  4. Redistribution and use in source and binary forms, with or without
  5. modification, are permitted provided that the following conditions are met:
  6. * Redistributions of source code must retain the above copyright
  7. notice, this list of conditions and the following disclaimer.
  8. * Redistributions in binary form must reproduce the above copyright
  9. notice, this list of conditions and the following disclaimer in the
  10. documentation and/or other materials provided with the distribution.
  11. * The name of Pierre-Olivier Latour may not be used to endorse
  12. or promote products derived from this software without specific
  13. prior written permission.
  14. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  15. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  16. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  17. DISCLAIMED. IN NO EVENT SHALL PIERRE-OLIVIER LATOUR BE LIABLE FOR ANY
  18. DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  19. (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20. LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  21. ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  23. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24. */
  25. #import <Foundation/Foundation.h>
  26. /**
  27. * Attribute key to retrieve an NSArray containing NSStrings from a GCDWebServerRequest
  28. * with the contents of any regular expression captures done on the request path.
  29. *
  30. * @warning This attribute will only be set on the request if adding a handler using
  31. * -addHandlerForMethod:pathRegex:requestClass:processBlock:.
  32. */
  33. extern NSString* const GCDWebServerRequestAttribute_RegexCaptures;
  34. /**
  35. * This protocol is used by the GCDWebServerConnection to communicate with
  36. * the GCDWebServerRequest and write the received HTTP body data.
  37. *
  38. * Note that multiple GCDWebServerBodyWriter objects can be chained together
  39. * internally e.g. to automatically decode gzip encoded content before
  40. * passing it on to the GCDWebServerRequest.
  41. *
  42. * @warning These methods can be called on any GCD thread.
  43. */
  44. @protocol GCDWebServerBodyWriter <NSObject>
  45. /**
  46. * This method is called before any body data is received.
  47. *
  48. * It should return YES on success or NO on failure and set the "error" argument
  49. * which is guaranteed to be non-NULL.
  50. */
  51. - (BOOL)open:(NSError**)error;
  52. /**
  53. * This method is called whenever body data has been received.
  54. *
  55. * It should return YES on success or NO on failure and set the "error" argument
  56. * which is guaranteed to be non-NULL.
  57. */
  58. - (BOOL)writeData:(NSData*)data error:(NSError**)error;
  59. /**
  60. * This method is called after all body data has been received.
  61. *
  62. * It should return YES on success or NO on failure and set the "error" argument
  63. * which is guaranteed to be non-NULL.
  64. */
  65. - (BOOL)close:(NSError**)error;
  66. @end
  67. /**
  68. * The GCDWebServerRequest class is instantiated by the GCDWebServerConnection
  69. * after the HTTP headers have been received. Each instance wraps a single HTTP
  70. * request. If a body is present, the methods from the GCDWebServerBodyWriter
  71. * protocol will be called by the GCDWebServerConnection to receive it.
  72. *
  73. * The default implementation of the GCDWebServerBodyWriter protocol on the class
  74. * simply ignores the body data.
  75. *
  76. * @warning GCDWebServerRequest instances can be created and used on any GCD thread.
  77. */
  78. @interface GCDWebServerRequest : NSObject <GCDWebServerBodyWriter>
  79. /**
  80. * Returns the HTTP method for the request.
  81. */
  82. @property(nonatomic, readonly) NSString* method;
  83. /**
  84. * Returns the URL for the request.
  85. */
  86. @property(nonatomic, readonly) NSURL* URL;
  87. /**
  88. * Returns the HTTP headers for the request.
  89. */
  90. @property(nonatomic, readonly) NSDictionary* headers;
  91. /**
  92. * Returns the path component of the URL for the request.
  93. */
  94. @property(nonatomic, readonly) NSString* path;
  95. /**
  96. * Returns the parsed and unescaped query component of the URL for the request.
  97. *
  98. * @warning This property will be nil if there is no query in the URL.
  99. */
  100. @property(nonatomic, readonly) NSDictionary* query;
  101. /**
  102. * Returns the content type for the body of the request parsed from the
  103. * "Content-Type" header.
  104. *
  105. * This property will be nil if the request has no body or set to
  106. * "application/octet-stream" if a body is present but there was no
  107. * "Content-Type" header.
  108. */
  109. @property(nonatomic, readonly) NSString* contentType;
  110. /**
  111. * Returns the content length for the body of the request parsed from the
  112. * "Content-Length" header.
  113. *
  114. * This property will be set to "NSUIntegerMax" if the request has no body or
  115. * if there is a body but no "Content-Length" header, typically because
  116. * chunked transfer encoding is used.
  117. */
  118. @property(nonatomic, readonly) NSUInteger contentLength;
  119. /**
  120. * Returns the parsed "If-Modified-Since" header or nil if absent or malformed.
  121. */
  122. @property(nonatomic, readonly) NSDate* ifModifiedSince;
  123. /**
  124. * Returns the parsed "If-None-Match" header or nil if absent or malformed.
  125. */
  126. @property(nonatomic, readonly) NSString* ifNoneMatch;
  127. /**
  128. * Returns the parsed "Range" header or (NSUIntegerMax, 0) if absent or malformed.
  129. * The range will be set to (offset, length) if expressed from the beginning
  130. * of the entity body, or (NSUIntegerMax, length) if expressed from its end.
  131. */
  132. @property(nonatomic, readonly) NSRange byteRange;
  133. /**
  134. * Returns YES if the client supports gzip content encoding according to the
  135. * "Accept-Encoding" header.
  136. */
  137. @property(nonatomic, readonly) BOOL acceptsGzipContentEncoding;
  138. /**
  139. * Returns the address of the local peer (i.e. server) for the request
  140. * as a raw "struct sockaddr".
  141. */
  142. @property(nonatomic, readonly) NSData* localAddressData;
  143. /**
  144. * Returns the address of the local peer (i.e. server) for the request
  145. * as a string.
  146. */
  147. @property(nonatomic, readonly) NSString* localAddressString;
  148. /**
  149. * Returns the address of the remote peer (i.e. client) for the request
  150. * as a raw "struct sockaddr".
  151. */
  152. @property(nonatomic, readonly) NSData* remoteAddressData;
  153. /**
  154. * Returns the address of the remote peer (i.e. client) for the request
  155. * as a string.
  156. */
  157. @property(nonatomic, readonly) NSString* remoteAddressString;
  158. /**
  159. * This method is the designated initializer for the class.
  160. */
  161. - (instancetype)initWithMethod:(NSString*)method url:(NSURL*)url headers:(NSDictionary*)headers path:(NSString*)path query:(NSDictionary*)query;
  162. /**
  163. * Convenience method that checks if the contentType property is defined.
  164. */
  165. - (BOOL)hasBody;
  166. /**
  167. * Convenience method that checks if the byteRange property is defined.
  168. */
  169. - (BOOL)hasByteRange;
  170. /**
  171. * Retrieves an attribute associated with this request using the given key.
  172. *
  173. * @return The attribute value for the key.
  174. */
  175. - (id)attributeForKey:(NSString*)key;
  176. @end