Web server CGI interface - SC12 @CHIP-RTOS V1.10
IPC@CHIP Documentation Index CGI API News
The CGI ("Common Gateway Interface") API uses interrupt 0xAB with a service number in the high order byte of the AX register (AH). This interface provides access to the CGI implementation of the IPC@CHIP Web server.
CGI at the IPC@CHIP provides the possibility to install at the IPC@CHIP Web server own programmed CGI functions. These functions are bound with a fixed name and are executed by the Web server task, if a http request with such a fixed name comes in. This mechanism allows dynamic usage of the IPC@CHIP Web server. For better understanding of CGI and possibilities for using, see description of available program examples at the example link below.
File Upload:
Also there is a possibility to upload files to the @CHIP's disk. This does not use the CGI interface but the Web server. Therefore you only need a defined HTML formular which sends the required data to the @CHIP Web server. An example can be found in the CGI Example Zip file.
Notes:
- For test and demonstration purpose two pages are preinstalled at the IPC@CHIP:
a)main.htm: Static html introduction page.
b)chipcfg : Dynamic page with system time/date and configuration data of the requested IPC@CHIP. - For configuring the webserver and CGI, see the provided chip.ini entries.
-
For some useful comments see also under Programming notes
Topics
- Web Server Overview
Web Server File Types
CGI API News
CGI API Error Codes
CGI API Developer Notes
CGI API Examples Available
CGI API Data Structures
Interrupt 0xAB service 0x01: CGI_INSTALL, Install a CGI function
Parameters
- AH
- 0x01 (= CGI_INSTALL)
- DX:SI
- Pointer to a temporary CGI_Entry
type structure.
Return Value
- DX =0 success AX: 0
DX!=0 failure AX: contains error code CGI_NO_FREE_ENTRY or CGI_INVALID_METHOD
Comments
- This API function makes no copy of the information in the provided CGI_Entry structure, so your structure at [DX:SI] must be persistent. The maximum number of available CGI pages is configurable at the chip.ini file, see CGI entries.
Related Topics
- CGI API Error Codes
- cgistat
command line
- CGI_INSTALL_PAS API Function, for Pascal CGI Procedures
Top of list
Index page
Interrupt 0xAB service 0x02: CGI_REMOVE, Remove a CGI function
Parameters
- AH
- 0x02 (= CGI_REMOVE)
- DX:SI
- Pointer to the null terminated URL path name
Return Value
- DX =0 success AX: 0
DX!=0 failure AX: contains error code CGI_NOT_FOUND
Comments
- The CGI function to be deleted is identified by the provided
URL string.
It is also possible to remove the two predefined cgi functions
main.htm
and chipcfg
from the table.
Related Topics
Top of list
Index page
Interrupt 0xAB service 0x03: CGI_SETMAIN, Set a new main page
Parameters
- AH
- 0x03 (= CGI_SETMAIN)
- DX:SI
- Pointer to name of new main page
Return Value
- DX =0 success AX: 0
DX!=0 failure AX: error code CGI_INVALID_NAME
Comments
- The string at [DX:SI] is null terminated with a maximum length of 64 characters (not counting the terminating zero).
Related Topics
- CGI_GETMAIN API Function
- CGI API Error Codes
Top of list
Index page
Interrupt 0xAB service 0x04: CGI_SETROOTDIR, Set Web server's root directory
Parameters
- AH
- 0x04 (= CGI_SETROOTDIR)
- DX:SI
- Pointer to the name of new root directory
Return Value
- DX =0 success AX: 0
DX!=0 failure AX: error code CGI_INVALID_DIR
Comments
- The string at [DX:SI] is null terminated with a maximum length of 64 characters (not counting the terminating zero). The root directory is also configurable at the chip.ini file, see ROOTDIR and DRIVE.
Related Topics
- CGI_GETROOTDIR API Function
- CGI API Error Codes
Top of list
Index page
Interrupt 0xAB service 0x05: CGI_GETROOTDIR, Get Web server's root directory
Parameters
- AH
- 0x05 (= CGI_GETROOTDIR)
Return Value
- DX=0 AX=0 , ES:DI contains pointer to root directory name
Comments
- The string referenced by [ES:DI] is null terminated and is in the RTOS's data space.
Related Topics
- CGI_SETROOTDIR API Function
Top of list
Index page
Interrupt 0xAB service 0x06: CGI_GETMAIN, Get main page name
Parameters
- AH
- 0x06 (= CGI_GETMAIN)
Return Value
- DX=0 AX=0 , ES:DI contains pointer to current main page name
Comments
- The string referenced by [ES:DI] is null terminated and is in the RTOS's data space.
Related Topics
- CGI_SETMAIN API Function
Top of list
Index page
Interrupt 0xAB service 0x07: CGI_GETFORMITEM, Split a formular into name and value
- Parse the argument buffer to obtain name and value.
Parameters
- AH
- 0x07 (= CGI_GETFORMITEM)
- BX:SI
- Pointer to argument buffer to be parsed.
- ES:DI
- Pointer to a FormItem
type structure
Return Value
- DX=0 AX=0, User buffers referenced by pointers in
FormItem structure at [ES:DI] are filled in
with name and value
Comments
- On initial call, the argument buffer pointer provided by the caller
in BX:SI is a copy of the fArgumentBufferPtr member of
the rbCgi
structure passed by the
Web server to the CGI callback function. On subsequent calls here
to pick up additional formular, the pointer returned from the
CGI_FINDNEXTITEM API call can be used here.
The caller must set the two members of the FormItem structure prior to calling here. Both pointers reference buffers allocated by the user, which will receive strings produced by this API call.
For preventing internal buffer overruns, the user should provide 64 bytes of buffer addressed by FormItem.NamePtr and 256 bytes pointed by FormItem.ValuePtr. The max. size for a full pathname (pagename+complete argumentbuffer)
e.g. "example?Name1=Value1&Name2=Value2"
is 256 bytes. Because of this behaviour, the storage addressed by FormItem.ValuePtr must have the max. size of a full pathname (256 bytes).
See example submit.c.
Related Topics
- CGI_FINDNEXTITEM API Function
Top of list
Index page
Interrupt 0xAB service 0x08: CGI_FINDNEXTITEM, Return the address of the next formular tag
- Most formulars have more than one item, this function searches for the next form item in a CGI request argument string. This function can only be used after a CGIFORMITEM API call. (See example submit2.c)
Parameters
- AH
- 0x08 (= CGI_FINDNEXTITEM)
- BX:SI
- CGI request argument pointer
Return Value
- DX=0 AX=0, ES:DI: pointer to the found item
DX=-1 AX=0, no next item was found
Comments
- The CGI request argument buffer pointer provided by the caller in BX:SI is
initially taken from the rbCgi structure passed by the Web
server to the CGI callback function.
This function scans the buffer at [BX:SI] for an ampersand character, '&', and if found returns a pointer to the character in the string following the ampersand.
The strings must be null terminated.
Related Topics
- CGI_GETFORMITEM API Function
Top of list
Index page
Interrupt 0xAB service 0x09: CGI_INSTALL_PAS, Install a Turbo Pascal CGI procedure
- Special install function for Turbo Pascal CGI procedures
Parameters
- AH
- 0x09 (= CGI_INSTALL_PAS)
- DX:SI
- Pointer to a temporary CGI_Entry
type structure.
Return Value
- DX =0 success AX: 0
DX!=0 failure AX: contains error code CGI_NO_FREE_ENTRY or CGI_INVALID_METHOD
Comments
- This API function makes a copy of the information in the provided CGI_Entry structure, so your structure at [DX:SI] need not be persistent.
Related Topics
- CGI_INSTALL API Function, for C CGI Procedures
Top of list
Index page
End of document