IOS Streaming Browser 1.0
An IOS streaming browser to stream the display to others or to a projector

/Users/willrubel/IOS-Streaming-Browser/IOS-Streaming-Browser/HTTPResponse.h

Go to the documentation of this file.
00001 #import <Foundation/Foundation.h>
00002 
00003 
00004 @protocol HTTPResponse
00005 
00006 /**
00007  * Gets the length of the HTTP response content length in bytes.
00008  * If you don't know the length in advance, implement the isChunked method and have it return YES.
00009     returns UInt64
00010 **/
00011 - (UInt64)contentLength;
00012 
00013 /**
00014  * The HTTP server supports range requests in order to allow things like
00015  * file download resumption and optimized streaming on mobile devices.
00016     returns UInt64
00017 **/
00018 - (UInt64)offset;
00019 
00020 /**
00021     Sets the offset
00022     param UInt64
00023 **/
00024 - (void)setOffset:(UInt64)offset;
00025 
00026 /**
00027  * Returns the data for the response.
00028  * You do not have to return data of the exact length that is given.
00029  * You may optionally return data of a lesser length.
00030  * However, you must never return data of a greater length than requested.
00031  * Doing so could disrupt proper support for range requests.
00032  * 
00033  * To support asynchronous responses, read the discussion at the bottom of this header.
00034 **/
00035 - (NSData *)readDataOfLength:(NSUInteger)length;
00036 
00037 /**
00038  * Should only return YES after the HTTPConnection has read all available data.
00039  * That is, all data for the response has been returned to the HTTPConnection via the readDataOfLength method.
00040 **/
00041 - (BOOL)isDone;
00042 
00043 @optional
00044 
00045 /**
00046  * If you need time to calculate any part of the HTTP response headers (status code or header fields),
00047  * this method allows you to delay sending the headers so that you may asynchronously execute the calculations.
00048  * Simply implement this method and return YES until you have everything you need concerning the headers.
00049  * 
00050  * This method ties into the asynchronous response architecture of the HTTPConnection.
00051  * You should read the full discussion at the bottom of this header.
00052  * 
00053  * If you return YES from this method,
00054  * the HTTPConnection will wait for you to invoke the responseHasAvailableData method.
00055  * After you do, the HTTPConnection will again invoke this method to see if the response is ready to send the headers.
00056  * 
00057  * You should only delay sending the headers until you have everything you need concerning just the headers.
00058  * Asynchronously generating the body of the response is not an excuse to delay sending the headers.
00059  * Instead you should tie into the asynchronous response architecture, and use techniques such as the isChunked method.
00060  * 
00061  * Important: You should read the discussion at the bottom of this header.
00062 **/
00063 - (BOOL)delayResponeHeaders;
00064 
00065 /**
00066  * Status code for response.
00067  * Allows for responses such as redirect (301), etc.
00068 **/
00069 - (NSInteger)status;
00070 
00071 /**
00072  * If you want to add any extra HTTP headers to the response,
00073  * simply return them in a dictionary in this method.
00074 **/
00075 - (NSDictionary *)httpHeaders;
00076 
00077 /**
00078  * If you don't know the content-length in advance,
00079  * implement this method in your custom response class and return YES.
00080  * 
00081  * Important: You should read the discussion at the bottom of this header.
00082 **/
00083 - (BOOL)isChunked;
00084 
00085 /**
00086  * This method is called from the HTTPConnection class when the connection is closed,
00087  * or when the connection is finished with the response.
00088  * If your response is asynchronous, you should implement this method so you know not to
00089  * invoke any methods on the HTTPConnection after this method is called (as the connection may be deallocated).
00090 **/
00091 - (void)connectionDidClose;
00092 
00093 @end
00094 
00095 
00096 /**
00097  * Important notice to those implementing custom asynchronous and/or chunked responses:
00098  * 
00099  * HTTPConnection supports asynchronous responses.  All you have to do in your custom response class is
00100  * asynchronously generate the response, and invoke HTTPConnection's responseHasAvailableData method.
00101  * You don't have to wait until you have all of the response ready to invoke this method.  For example, if you
00102  * generate the response in incremental chunks, you could call responseHasAvailableData after generating
00103  * each chunk.  Please see the HTTPAsyncFileResponse class for an example of how to do this.
00104  * 
00105  * The normal flow of events for an HTTPConnection while responding to a request is like this:
00106  *  - Send http resopnse headers
00107  *  - Get data from response via readDataOfLength method.
00108  *  - Add data to asyncSocket's write queue.
00109  *  - Wait for asyncSocket to notify it that the data has been sent.
00110  *  - Get more data from response via readDataOfLength method.
00111  *  - ... continue this cycle until the entire response has been sent.
00112  * 
00113  * With an asynchronous response, the flow is a little different.
00114  * 
00115  * First the HTTPResponse is given the opportunity to postpone sending the HTTP response headers.
00116  * This allows the response to asynchronously execute any code needed to calculate a part of the header.
00117  * An example might be the response needs to generate some custom header fields,
00118  * or perhaps the response needs to look for a resource on network-attached storage.
00119  * Since the network-attached storage may be slow, the response doesn't know whether to send a 200 or 404 yet.
00120  * In situations such as this, the HTTPResponse simply implements the delayResponseHeaders method and returns YES.
00121  * After returning YES from this method, the HTTPConnection will wait until the response invokes its
00122  * responseHasAvailableData method. After this occurs, the HTTPConnection will again query the delayResponseHeaders
00123  * method to see if the response is ready to send the headers.
00124  * This cycle will continue until the delayResponseHeaders method returns NO.
00125  * 
00126  * You should only delay sending the response headers until you have everything you need concerning just the headers.
00127  * Asynchronously generating the body of the response is not an excuse to delay sending the headers.
00128  * 
00129  * After the response headers have been sent, the HTTPConnection calls your readDataOfLength method.
00130  * You may or may not have any available data at this point. If you don't, then simply return nil.
00131  * You should later invoke HTTPConnection's responseHasAvailableData when you have data to send.
00132  * 
00133  * You don't have to keep track of when you return nil in the readDataOfLength method, or how many times you've invoked
00134  * responseHasAvailableData. Just simply call responseHasAvailableData whenever you've generated new data, and
00135  * return nil in your readDataOfLength whenever you don't have any available data in the requested range.
00136  * HTTPConnection will automatically detect when it should be requesting new data and will act appropriately.
00137  * 
00138  * It's important that you also keep in mind that the HTTP server supports range requests.
00139  * The setOffset method is mandatory, and should not be ignored.
00140  * Make sure you take into account the offset within the readDataOfLength method.
00141  * You should also be aware that the HTTPConnection automatically sorts any range requests.
00142  * So if your setOffset method is called with a value of 100, then you can safely release bytes 0-99.
00143  * 
00144  * HTTPConnection can also help you keep your memory footprint small.
00145  * Imagine you're dynamically generating a 10 MB response.  You probably don't want to load all this data into
00146  * RAM, and sit around waiting for HTTPConnection to slowly send it out over the network.  All you need to do
00147  * is pay attention to when HTTPConnection requests more data via readDataOfLength.  This is because HTTPConnection
00148  * will never allow asyncSocket's write queue to get much bigger than READ_CHUNKSIZE bytes.  You should
00149  * consider how you might be able to take advantage of this fact to generate your asynchronous response on demand,
00150  * while at the same time keeping your memory footprint small, and your application lightning fast.
00151  * 
00152  * If you don't know the content-length in advanced, you should also implement the isChunked method.
00153  * This means the response will not include a Content-Length header, and will instead use "Transfer-Encoding: chunked".
00154  * There's a good chance that if your response is asynchronous and dynamic, it's also chunked.
00155  * If your response is chunked, you don't need to worry about range requests.
00156 **/
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Properties Defines