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

Powered by WebSVN v2.8.3