?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /*********************************************************************
2 *
3 * HTTP Headers for Microchip TCP/IP Stack
4 *
5 *********************************************************************
6 * FileName: HTTP2.h
7 * Dependencies: None
8 * Processor: PIC18, PIC24F, PIC24H, dsPIC30F, dsPIC33F, PIC32
9 * Compiler: Microchip C32 v1.05 or higher
10 * Microchip C30 v3.12 or higher
11 * Microchip C18 v3.30 or higher
12 * HI-TECH PICC-18 PRO 9.63PL2 or higher
13 * Company: Microchip Technology, Inc.
14 *
15 * Software License Agreement
16 *
17 * Copyright (C) 2002-2009 Microchip Technology Inc. All rights
18 * reserved.
19 *
20 * Microchip licenses to you the right to use, modify, copy, and
21 * distribute:
22 * (i) the Software when embedded on a Microchip microcontroller or
23 * digital signal controller product ("Device") which is
24 * integrated into Licensee's product; or
25 * (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,
26 * ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device
27 * used in conjunction with a Microchip ethernet controller for
28 * the sole purpose of interfacing with the ethernet controller.
29 *
30 * You should refer to the license agreement accompanying this
31 * Software for additional information regarding your rights and
32 * obligations.
33 *
34 * THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT
35 * WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT
36 * LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A
37 * PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL
38 * MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR
39 * CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF
40 * PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS
41 * BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE
42 * THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER
43 * SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT
44 * (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.
45 *
46 *
47 * Author Date Comment
48 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
49 * Nilesh Rajbharti 8/14/01 Original
50 * Elliott Wood 6/4/07 Complete rewrite (known as HTTP2)
51 * Amit Shirbhate 11/12/09 Modified for MDD File System Support
52 ********************************************************************/
53  
54 #ifndef __HTTP2_H
55 #define __HTTP2_H
56  
57 #include "TCPIP Stack/TCPIP.h"
58  
59 #if defined(STACK_USE_HTTP2_SERVER)
60  
61 /****************************************************************************
62 Section:
63 Server Configuration Settings
64 ***************************************************************************/
65  
66 #if !defined(HTTP_PORT)
67 #define HTTP_PORT (80u) // Listening port for HTTP server
68 #endif
69 #if !defined(HTTPS_PORT)
70 #define HTTPS_PORT (443u) // Listening port for HTTPS server (when SSL enabled)
71 #endif
72 #if !defined(HTTP_MAX_DATA_LEN)
73 #define HTTP_MAX_DATA_LEN (100u)
74 #endif
75 #if !defined(HTTP_MIN_CALLBACK_FREE)
76 #define HTTP_MIN_CALLBACK_FREE (16u)
77 #endif
78 #define HTTP_CACHE_LEN ("600") // Max lifetime (sec) of static responses as string
79 #define HTTP_TIMEOUT (45u) // Max time (sec) to await more data before
80  
81 // Authentication requires Base64 decoding
82 #if defined(HTTP_USE_AUTHENTICATION)
83 #ifndef STACK_USE_BASE64_DECODE
84 #define STACK_USE_BASE64_DECODE
85 #endif
86 #endif
87  
88 /****************************************************************************
89 Section:
90 Commands and Server Responses
91 ***************************************************************************/
92  
93 //Supported Commands and Server Response Codes
94 typedef enum
95 {
96 HTTP_GET = 0u, // GET command is being processed
97 HTTP_POST, // POST command is being processed
98 HTTP_BAD_REQUEST, // 400 Bad Request will be returned
99 HTTP_UNAUTHORIZED, // 401 Unauthorized will be returned
100 HTTP_NOT_FOUND, // 404 Not Found will be returned
101 HTTP_OVERFLOW, // 414 Request-URI Too Long will be returned
102 HTTP_INTERNAL_SERVER_ERROR, // 500 Internal Server Error will be returned
103 HTTP_NOT_IMPLEMENTED, // 501 Not Implemented (not a GET or POST command)
104 #if defined(HTTP_MPFS_UPLOAD)
105 HTTP_MPFS_FORM, // Show the MPFS Upload form
106 HTTP_MPFS_UP, // An MPFS Upload is being processed
107 HTTP_MPFS_OK, // An MPFS Upload was successful
108 HTTP_MPFS_ERROR, // An MPFS Upload was not a valid image
109 #endif
110 HTTP_REDIRECT, // 302 Redirect will be returned
111 HTTP_SSL_REQUIRED // 403 Forbidden is returned, indicating SSL is required
112 } HTTP_STATUS;
113  
114 /****************************************************************************
115 Section:
116 HTTP State Definitions
117 ***************************************************************************/
118  
119 // Basic HTTP Connection State Machine
120 typedef enum
121 {
122 SM_HTTP_IDLE = 0u, // Socket is idle
123 SM_HTTP_PARSE_REQUEST, // Parses the first line for a file name and GET args
124 SM_HTTP_PARSE_HEADERS, // Reads and parses headers one at a time
125 SM_HTTP_AUTHENTICATE, // Validates the current authorization state
126 SM_HTTP_PROCESS_GET, // Invokes user callback for GET args or cookies
127 SM_HTTP_PROCESS_POST, // Invokes user callback for POSTed data
128 SM_HTTP_PROCESS_REQUEST, // Begins the process of returning data
129 SM_HTTP_SERVE_HEADERS, // Sends any required headers for the response
130 SM_HTTP_SERVE_COOKIES, // Adds any cookies to the response
131 SM_HTTP_SERVE_BODY, // Serves the actual content
132 SM_HTTP_SEND_FROM_CALLBACK, // Invokes a dynamic variable callback
133 SM_HTTP_DISCONNECT // Disconnects the server and closes all files
134 } SM_HTTP2;
135  
136 // Result states for execution callbacks
137 typedef enum
138 {
139 HTTP_IO_DONE = 0u, // Finished with procedure
140 HTTP_IO_NEED_DATA, // More data needed to continue, call again later
141 HTTP_IO_WAITING // Waiting for asynchronous process to complete, call again later
142 } HTTP_IO_RESULT;
143  
144 // Result states for HTTPPostReadName and HTTPPostReadValue
145 typedef enum
146 {
147 HTTP_READ_OK = 0u, // Read was successful
148 HTTP_READ_TRUNCATED, // Buffer overflow prevented by truncating value
149 HTTP_READ_INCOMPLETE // Entire object is not yet in the buffer. Try again later.
150 } HTTP_READ_STATUS;
151  
152 // File type definitions
153 typedef enum
154 {
155 HTTP_TXT = 0u, // File is a text document
156 HTTP_HTM, // File is HTML (extension .htm)
157 HTTP_HTML, // File is HTML (extension .html)
158 HTTP_CGI, // File is HTML (extension .cgi)
159 HTTP_XML, // File is XML (extension .xml)
160 HTTP_CSS, // File is stylesheet (extension .css)
161 HTTP_GIF, // File is GIF image (extension .gif)
162 HTTP_PNG, // File is PNG image (extension .png)
163 HTTP_JPG, // File is JPG image (extension .jpg)
164 HTTP_JAVA, // File is java (extension .java)
165 HTTP_WAV, // File is audio (extension .wav)
166 HTTP_UNKNOWN // File type is unknown
167 } HTTP_FILE_TYPE;
168  
169 // HTTP Connection Struct
170 // Stores partial state data for each connection
171 // Meant for storage in fast access RAM
172 typedef struct
173 {
174 SM_HTTP2 sm; // Current connection state
175 TCP_SOCKET socket; // Socket being served
176 } HTTP_STUB;
177  
178 #define sktHTTP httpStubs[curHTTPID].socket // Access the current socket
179  
180 // Stores extended state data for each connection
181 typedef struct
182 {
183 DWORD byteCount; // How many bytes have been read so far
184 DWORD nextCallback; // Byte index of the next callback
185 DWORD callbackID; // Callback ID to execute, also used as watchdog timer
186 DWORD callbackPos; // Callback position indicator
187 BYTE *ptrData; // Points to first free byte in data
188 BYTE *ptrRead; // Points to current read location
189 FILE_HANDLE file; // File pointer for the file being served
190 FILE_HANDLE offsets; // File pointer for any offset info being used
191 BYTE hasArgs; // True if there were get or cookie arguments
192 BYTE isAuthorized; // 0x00-0x79 on fail, 0x80-0xff on pass
193 HTTP_STATUS httpStatus; // Request method/status
194 HTTP_FILE_TYPE fileType; // File type to return with Content-Type
195 BYTE data[HTTP_MAX_DATA_LEN]; // General purpose data buffer
196 #if defined(HTTP_USE_POST)
197 BYTE smPost; // POST state machine variable
198 #endif
199 } HTTP_CONN;
200  
201 #define RESERVED_HTTP_MEMORY ( (DWORD)MAX_HTTP_CONNECTIONS * (DWORD)sizeof(HTTP_CONN))
202  
203 /****************************************************************************
204 Section:
205 Global HTTP Variables
206 ***************************************************************************/
207  
208 extern HTTP_CONN curHTTP;
209 extern HTTP_STUB httpStubs[MAX_HTTP_CONNECTIONS];
210 extern BYTE curHTTPID;
211  
212 /****************************************************************************
213 Section:
214 Function Prototypes
215 ***************************************************************************/
216  
217 void HTTPInit(void);
218 void HTTPServer(void);
219 BYTE* HTTPURLDecode(BYTE* cData);
220 BYTE* HTTPGetArg(BYTE* cData, BYTE* cArg);
221 void HTTPIncFile(ROM BYTE* cFile);
222  
223 #if defined(__18CXX)
224 BYTE* HTTPGetROMArg(BYTE* cData, ROM BYTE* cArg);
225 #else
226 // Non-ROM variant for C30 / C32
227 #define HTTPGetROMArg(a,b) HTTPGetArg(a,(BYTE*)b)
228 #endif
229  
230 #if defined(HTTP_USE_POST)
231 HTTP_READ_STATUS HTTPReadPostName(BYTE* cData, WORD wLen);
232 HTTP_READ_STATUS HTTPReadPostValue(BYTE* cData, WORD wLen);
233 #endif
234  
235 /*****************************************************************************
236 Function:
237 HTTP_READ_STATUS HTTPReadPostPair(BYTE* cData, WORD wLen)
238  
239 Summary:
240 Reads a name and value pair from a URL encoded string in the TCP buffer.
241  
242 Description:
243 Reads a name and value pair from a URL encoded string in the TCP buffer.
244 This function is meant to be called from an HTTPExecutePost callback to
245 facilitate easier parsing of incoming data. This function also prevents
246 buffer overflows by forcing the programmer to indicate how many bytes are
247 expected. At least 2 extra bytes are needed in cData over the maximum
248 length of data expected to be read.
249  
250 This function will read until the next '&' character, which indicates the
251 end of a value parameter. It assumes that the front of the buffer is
252 the beginning of the name paramter to be read.
253  
254 This function properly updates curHTTP.byteCount by decrementing it
255 by the number of bytes read. It also removes the delimiting '&' from
256 the buffer.
257  
258 Once complete, two strings will exist in the cData buffer. The first is
259 the parameter name that was read, while the second is the associated
260 value.
261  
262 Precondition:
263 Front of TCP buffer is the beginning of a name parameter, and the rest of
264 the TCP buffer contains a URL-encoded string with a name parameter
265 terminated by a '=' character and a value parameter terminated by a '&'.
266  
267 Parameters:
268 cData - where to store the name and value strings once they are read
269 wLen - how many bytes can be written to cData
270  
271 Return Values:
272 HTTP_READ_OK - name and value were successfully read
273 HTTP_READ_TRUNCTATED - entire name and value could not fit in the buffer,
274 so input was truncated and data has been lost
275 HTTP_READ_INCOMPLETE - entire name and value was not yet in the buffer,
276 so call this function again later to retrieve
277  
278 Remarks:
279 This function is aliased to HTTPReadPostValue, since they effectively
280 perform the same task. The name is provided only for completeness.
281 ***************************************************************************/
282 #define HTTPReadPostPair(cData, wLen) HTTPReadPostValue(cData, wLen)
283  
284  
285 /****************************************************************************
286 Section:
287 User-Implemented Callback Function Prototypes
288 ***************************************************************************/
289  
290 /*****************************************************************************
291 Function:
292 HTTP_IO_RESULT HTTPExecuteGet(void)
293  
294 Summary:
295 Processes GET form field variables and cookies.
296  
297 Description:
298 This function is implemented by the application developer in
299 CustomHTTPApp.c. Its purpose is to parse the data received from
300 URL parameters (GET method forms) and cookies and perform any
301 application-specific tasks in response to these inputs. Any
302 required authentication has already been validated.
303  
304 When this function is called, curHTTP.data contains sequential
305 name/value pairs of strings representing the data received. In this
306 format, HTTPGetArg and HTTPGetROMArg can be used to search for
307 specific variables in the input. If data buffer space associated
308 with this connection is required, curHTTP.data may be overwritten
309 here once the application is done with the values. Any data placed
310 there will be available to future callbacks for this connection,
311 including HTTPExecutePost and any HTTPPrint_varname dynamic
312 substitutions.
313  
314 This function may also issue redirections by setting curHTTP.data
315 to the destination file name or URL, and curHTTP.httpStatus to
316 HTTP_REDIRECT.
317  
318 Finally, this function may set cookies. Set curHTTP.data to a series
319 of name/value string pairs (in the same format in which parameters
320 arrive) and then set curHTTP.hasArgs equal to the number of cookie
321 name/value pairs. The cookies will be transmitted to the browser,
322 and any future requests will have those values available in
323 curHTTP.data.
324  
325 Precondition:
326 None
327  
328 Parameters:
329 None
330  
331 Return Values:
332 HTTP_IO_DONE - application is done processing
333 HTTP_IO_NEED_DATA - this value may not be returned because more data
334 will not become available
335 HTTP_IO_WAITING - the application is waiting for an asynchronous
336 process to complete, and this function should be
337 called again later
338  
339 Remarks:
340 This function is only called if variables are received via URL
341 parameters or Cookie arguments. This function may NOT write to the
342 TCP buffer.
343  
344 This function may service multiple HTTP requests simultaneously.
345 Exercise caution when using global or static variables inside this
346 routine. Use curHTTP.callbackPos or curHTTP.data for storage associated
347 with individual requests.
348 ***************************************************************************/
349 HTTP_IO_RESULT HTTPExecuteGet(void);
350  
351 /*****************************************************************************
352 Function:
353 HTTP_IO_RESULT HTTPExecutePost(void)
354  
355 Summary:
356 Processes POST form variables and data.
357  
358 Description:
359 This function is implemented by the application developer in
360 CustomHTTPApp.c. Its purpose is to parse the data received from
361 POST forms and perform any application-specific tasks in response
362 to these inputs. Any required authentication has already been
363 validated before this function is called.
364  
365 When this function is called, POST data will be waiting in the
366 TCP buffer. curHTTP.byteCount will indicate the number of bytes
367 remaining to be received before the browser request is complete.
368  
369 Since data is still in the TCP buffer, the application must call
370 TCPGet or TCPGetArray in order to retrieve bytes. When this is done,
371 curHTTP.byteCount MUST be updated to reflect how many bytes now
372 remain. The functions TCPFind, TCPFindString, TCPFindROMString,
373 TCPFindArray, and TCPFindROMArray may be helpful to locate data
374 in the TCP buffer.
375  
376 In general, data submitted from web forms via POST is URL encoded.
377 The HTTPURLDecode function can be used to decode this information
378 back to a standard string if required. If data buffer space
379 associated with this connection is required, curHTTP.data may be
380 overwritten here once the application is done with the values.
381 Any data placed there will be available to future callbacks for
382 this connection, including HTTPExecutePost and any
383 HTTPPrint_varname dynamic substitutions.
384  
385 Whenever a POST form is processed it is recommended to issue a
386 redirect back to the browser, either to a status page or to
387 the same form page that was posted. This prevents accidental
388 duplicate submissions (by clicking refresh or back/forward) and
389 avoids browser warnings about "resubmitting form data". Redirects
390 may be issued to the browser by setting curHTTP.data to the
391 destination file or URL, and curHTTP.httpStatus to HTTP_REDIRECT.
392  
393 Finally, this function may set cookies. Set curHTTP.data to a series
394 of name/value string pairs (in the same format in which parameters
395 arrive) and then set curHTTP.hasArgs equal to the number of cookie
396 name/value pairs. The cookies will be transmitted to the browser,
397 and any future requests will have those values available in
398 curHTTP.data.
399  
400 Precondition:
401 None
402  
403 Parameters:
404 None
405  
406 Return Values:
407 HTTP_IO_DONE - application is done processing
408 HTTP_IO_NEED_DATA - more data is needed to continue, and this
409 function should be called again later
410 HTTP_IO_WAITING - the application is waiting for an asynchronous
411 process to complete, and this function should
412 be called again later
413  
414 Remarks:
415 This function is only called when the request method is POST, and is
416 only used when HTTP_USE_POST is defined. This method may NOT write
417 to the TCP buffer.
418  
419 This function may service multiple HTTP requests simultaneously.
420 Exercise caution when using global or static variables inside this
421 routine. Use curHTTP.callbackPos or curHTTP.data for storage associated
422 with individual requests.
423 ***************************************************************************/
424 #if defined(HTTP_USE_POST)
425 HTTP_IO_RESULT HTTPExecutePost(void);
426 #endif
427  
428 /*****************************************************************************
429 Function:
430 BYTE HTTPNeedsAuth(BYTE* cFile)
431  
432 Summary:
433 Determines if a given file name requires authentication
434  
435 Description:
436 This function is implemented by the application developer in
437 CustomHTTPApp.c. Its function is to determine if a file being
438 requested requires authentication to view. The user name and password,
439 if supplied, will arrive later with the request headers, and will be
440 processed at that time.
441  
442 Return values 0x80 - 0xff indicate that authentication is not required,
443 while values from 0x00 to 0x79 indicate that a user name and password
444 are required before proceeding. While most applications will only use a
445 single value to grant access and another to require authorization, the
446 range allows multiple "realms" or sets of pages to be protected, with
447 different credential requirements for each.
448  
449 The return value of this function is saved as curHTTP.isAuthorized, and
450 will be available to future callbacks, including HTTPCheckAuth and any
451 of the HTTPExecuteGet, HTTPExecutePost, or HTTPPrint_varname callbacks.
452  
453 Precondition:
454 None
455  
456 Parameters:
457 cFile - the name of the file being requested
458  
459 Return Values:
460 <= 0x79 - valid authentication is required
461 >= 0x80 - access is granted for this connection
462  
463 Remarks:
464 This function may NOT write to the TCP buffer.
465 ***************************************************************************/
466 #if defined(HTTP_USE_AUTHENTICATION)
467 BYTE HTTPNeedsAuth(BYTE* cFile);
468 #endif
469  
470 /*****************************************************************************
471 Function:
472 BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)
473  
474 Summary:
475 Performs validation on a specific user name and password.
476  
477 Description:
478 This function is implemented by the application developer in
479 CustomHTTPApp.c. Its function is to determine if the user name and
480 password supplied by the client are acceptable for this resource.
481  
482 The value of curHTTP.isAuthorized will be set to the previous return
483 value of HTTPRequiresAuthorization. This callback function can check
484 this value to determine if only specific user names or passwords will
485 be accepted for this resource.
486  
487 Return values 0x80 - 0xff indicate that the credentials were accepted,
488 while values from 0x00 to 0x79 indicate that authorization failed.
489 While most applications will only use a single value to grant access,
490 flexibility is provided to store multiple values in order to
491 indicate which user (or user's group) logged in.
492  
493 The return value of this function is saved as curHTTP.isAuthorized, and
494 will be available to future callbacks, including any of the
495 HTTPExecuteGet, HTTPExecutePost, or HTTPPrint_varname callbacks.
496  
497 Precondition:
498 None
499  
500 Parameters:
501 cUser - the user name supplied by the client
502 cPass - the password supplied by the client
503  
504 Return Values:
505 <= 0x79 - the credentials were rejected
506 >= 0x80 - access is granted for this connection
507  
508 Remarks:
509 This function is only called when an Authorization header is
510 encountered.
511  
512 This function may NOT write to the TCP buffer.
513 ***************************************************************************/
514 #if defined(HTTP_USE_AUTHENTICATION)
515 BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass);
516 #endif
517  
518 /*****************************************************************************
519 Function:
520 void HTTPPrint_varname(void)
521 void HTTPPrint_varname(WORD wParam1)
522 void HTTPPrint_varname(WORD wParam1, WORD wParam2, ...)
523  
524 Summary:
525 Inserts dynamic content into a web page
526  
527 Description:
528 Functions in this style are implemented by the application developer in
529 CustomHTTPApp.c. These functions generate dynamic content to be
530 inserted into web pages and other files returned by the HTTP2 server.
531  
532 Functions of this type are called when a dynamic variable is located
533 in a web page. (ie, ~varname~ ) The name between the tilde '~'
534 characters is appended to the base function name. In this example, the
535 callback would be named HTTPPrint_varname.
536  
537 The function prototype is located in your project's HTTPPrint.h, which
538 is automatically generated by the MPFS2 Utility. The prototype will
539 have WORD parameters included for each parameter passed in the dynamic
540 variable. For example, the variable "~myArray(2,6)~" will generate the
541 prototype "void HTTPPrint_varname(WORD, WORD);".
542  
543 When called, this function should write its output directly to the TCP
544 socket using any combination of TCPIsPutReady, TCPPut, TCPPutArray,
545 TCPPutString, TCPPutROMArray, and TCPPutROMString.
546  
547 Before calling, the HTTP2 server guarantees that at least
548 HTTP_MIN_CALLBACK_FREE bytes (defaults to 16 bytes) are free in the
549 output buffer. If the function is writing less than this amount, it
550 should simply write the data to the socket and return.
551  
552 In situations where a function needs to write more this amount, it
553 must manage its output state using curHTTP.callbackPos. This value
554 will be set to zero before the function is called. If the function is
555 managing its output state, it must set this to a non-zero value before
556 returning. Typically this is used to track how many bytes have been
557 written, or how many remain to be written. If curHTTP.callbackPos is
558 non-zero, the function will be called again when more buffer space is
559 available. Once the callback completes, set this value back to zero
560 to resume normal servicing of the request.
561  
562 Precondition:
563 None
564  
565 Parameters:
566 wParam1 - first parameter passed in the dynamic variable (if any)
567 wParam2 - second parameter passed in the dynamic variable (if any)
568 ... - additional parameters as necessary
569  
570 Returns:
571 None
572  
573 Remarks:
574 This function may service multiple HTTP requests simultaneously,
575 especially when managing its output state. Exercise caution when using
576 global or static variables inside this routine. Use curHTTP.callbackPos
577 or curHTTP.data for storage associated with individual requests.
578 ***************************************************************************/
579 #if defined(DOCUMENTATION_ONLY)
580 void HTTPPrint_varname(WORD wParam1, WORD wParam2, ...);
581 #endif
582  
583  
584 #endif
585 #endif
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3