![]() |
IOS Streaming Browser 1.0
An IOS streaming browser to stream the display to others or to a projector
|
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 **/