LCGI Functions
This chapter describes the LCGI application programming interface (API). The API consists of
functions that perform most of the common tasks required to generate dynamic web pages. The
API, defined in LCGI.H, includes the following types of functions:
- Environment variable access
- NLM registration and deregistration
- Logical memory file manipulation
- Log file generation
- Memory allocation
- NetWare locking
- CGI stream use
- URL manipulation
- Work pointer use
All LCGI functions return a status of either SUCCESS or a non-zero registered API error value.
Any module receiving an error status can have the associated error text displayed at the system
console by calling the CsLib NLS enabled output routine, CSSM_DisplaySysMsg. For example:
CSSM_DisplaySysMsg (CSSMC_LogOutput, // options
retCode, // API error code
"<optional caller ID>"); // identify yourself
Accessing Environment Variables
The functions in this class access and modify the environment variables. The environment variables
can be accessed in the Cgi_t data structure. This structure is passed from the Web Server to LCGI
NLMs and vice-versa. The LCGI NLMs can easily call the CgiEnvGet or CgiEnvPut functions to
access and modify the environment variables and associated values.
LONG CgiEnvGet (struct Cgi_t * cgiInfo, BYTE
* envVariable, BYTE ** envValue)
This function returns a pointer to the string associated with
the specified environment variable.
Only the associated environment variable string value is returned
and not the "<name =>" portion of the name=value duplet.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- envVariable
- [IN] Search key.
- envValue
- [OUT] If found, string associated with the envVariable.
The returned pointer addresses the first byte of the value portion of
the "name=value" pair. Also, the pointer addresses the actual string,
and therefore must not be "freed" by the caller.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_EnvVariableNotFound | The specified environment variable was not found. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the pointer to the byte string of
environment variable (envVariable), or the returned address of
environment value (envValue) do not point to valid memory. |
LONG CgiEnvListCreate (struct Cgi_t * cgiInfo,
BYTE *** envList)
This function creates an array of pointers to strings, each in
the name=value format. The caller is responsible for issuing
the CgiEnvListDestroy function to free this array of pointers
to strings.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- envList
- [OUT] Points to an array of pointers to strings.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the returned address of environment
list (envList) does not point to valid memory. |
LONG CgiEnvListDestroy (BYTE *** envList)
This function destroys the array of pointers to strings
created by the CgiEnvListCreate function.
Parameters
- envList
- [IN] Points to an array of pointers to strings.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The address of environment list (envList) does not point to valid
memory. |
LONG CgiEnvPut (struct Cgi_t * cgiInfo, BYTE
* envVariable, BYTE * envValue)
This function creates or modifies a name=value pair in the
CgiEnv structure. If a new name=value is being defined, a
new entry is created in the CgiEnv structure. Otherwise, the
new environment value will be used to modify the existing
environment value.
Parameters
- cgiInfo
- [IN] Pointer to environment block to modify.
- envVariable
- [IN] Pointer to the name portion of the name=value duplet.
- envValue
- [IN] Full text of value portion of the name=value duplet.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CEE_NoMemory | Unable to allocate requested dynamic memory. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the pointer to the byte string of the
environment variable (envVariable), or the address of the
environment value (envValue) does not point to valid memory. |
Registering LCGI NLMs
The functions in this class register and deregister LCGI NLMs.
LONG CgiExtDeReg (LONG cgiHandle)
This function must be called by the extension process' SIGTERM
handler during unload in order to deregister the process with the
NetWare Web Server, freeing up the entry's associated memory,
and more importantly, removing it from the table so its handler
(now removed) will be reloaded by the NetWare Web Server on
the next client request for that process.
Parameters
- cgiHandle
- [IN] The handle returned by the earlier call to CgiExtReg.
Return Value
| Value | Meaning |
| SUCCESS | Successful |
| Registered API error code | Unsuccessful |
LONG CgiExtReg (CgiRequest fpReqHndlr,
CgiUnload fpUnloadHndlr, LONG flag, LONG
*cgiHandle)
This function registers the calling module as an LCGI
extension processing NLM with the NetWare Web Server.
Parameters
- fpReqHndlr
- [IN] Pointer to LCGI NLM's request handler function.
- pUnloadHndlr
- [IN] Pointer to LCGI NLM's unload request handler.
- flags
- [IN] Bitmap of flags indicating various options available to
the server/process interface.
- CgiC_ParseHeaders
- Indicates to the server that this process should be
created as a parsed header style process.
- CgiC_IsSmpEnabled
- When set on CgiExtReg, the Web Server process
thread will be migrated to SMP prior to calling the
extensions request handler. Note that being SMP
enabled means that all thread processes are executing
in a logically pre-emptive operation system.
- cgiHandle
- [OUT] Returned as the registered module"s handle for the
deregistration routine. The cgiHandle is also used for
CgiMutexLock and CgiMutexUnlock.
Return Values
| Value | Meaning |
| SUCCESS | Successful. |
| CEE_NoMemory | Unable to allocate requested dynamic memory. |
| CgiE_ModuleAlreadyRegistered | The calling module has already registered with the Web
Server. |
| CSSME_TextPtrInvalid | The pointer to the LCGI NLM's request handler function
(fpReqHndlr),or the pointer to the LCGI NLM's unload
request handler function (fpUnloadHndlr), or the returned
address of the registered module's handle (cgiHandle) does
not point to valid memory. |
Manipulating Logical Memory Files
The functions in this class manipulate logical memory files.
LONG CgiFileClose (struct CgiFile_t **
fileInfo)
This function frees the logical memory file and the CgiFile
data structure. If filePath specifies the disk file and if
fileOptions has write access, write to the disk file and free
the logical memory file (the CgiFile data structure). (Both
filePath and fileOptions are parameters for the CgiFileOpen
function.)
Parameters
- fileInfo
- [I/O] On input, pointer to the fileInfo data structure. Pointer
is zeroed on return.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) does not point to valid memory. |
LONG CgiFileDataCat (struct CgiFile_t *
fileInfo, BYTE * appendData, LONG
appendDataLen)
This function appends the specified data to the end of the
memory file. When this operation is complete, the logical
memory current file position points to the new end of the file.
Use the CgiFileSeek function to reset the current logical
memory file position.
Parameters
- fileInfo
- [IN] Pointer to the data structure that describes the memory
file.
- appendData
- [IN] Pointer to the data to be appended.
- appendDataLen
- [IN] Number of bytes to append.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to append data buffer
(appendData) does not point to valid memory. |
LONG CgiFileDataDelete (struct CgiFile_t *
fileInfo, LONG * deleteOffset, LONG deleteLen)
This function deletes the data starting at deleteOffset in the
memory file, with the length specified by deleteLen. After
this operation, the logical memory current file position points
to the first byte past the last byte deleted.
Parameters
- fileInfo
- [IN] Pointer to the data structure that describes the memory
file, fileInfo.
- deleteOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical delete offset. Otherwise, the
file is repositioned as specified using the parameter to
indirectly specify the offset. On output, if the pointer is not
NULL, this parameter returns the logical location of the first
byte following the delete location.
- deleteLen
- [IN] Number of bytes to delete.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidOffset | The parameter deleteOffset is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) does not reference valid memory. |
LONG CgiFileDataFind (struct CgiFile_t *
fileInfo, LONG * searchOffset, BYTE *
searchData, LONG searchLen)
This function searches from the searchOffset of the logical
memory file for the data defined in the searchData
parameter with the length specified in the searchLen
parameter.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- searchOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical starting offset. Otherwise, this
parameter returns the logical offset of the first byte of search
data in the logical memory file and the logical memory
current file position is updated to the first byte of the
matching search data. On output, if the pointer is not NULL,
the logical offset of the found location is returned. If the data
is not found, this parameter contains -1 and the logical
memory current file position is NOT changed.
- searchData
- [IN] Pointer to the search data.
- searchLen
- [IN] The search data length.
Return Value
| Value | Meaning |
| SUCCESS | Successful or the data cannot be found. |
| CgiE_InvalidOffset | The parameter searchOffset is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo), or the address of searchOffset
(searchOffset), or the pointer to the search data (searchData) does
not point to valid memory. |
LONG CgiFileDataInsert (struct CgiFile_t *
fileInfo, LONG * insertOffset, BYTE *
insertData, LONG insertDataLen)
This function inserts data into the logical memory file.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- insertOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical insert offset. Otherwise, the file
is repositioned as specified. On output, if the pointer is not
NULL, the logical offset of the first byte following the
inserted data will be returned.
- insertData
- [IN] Pointer to the data to be inserted.
- insertDataLen
- [IN] The insert data length.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidOffset | The parameter insertOffset is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to the insert data
(insertData) does not point to valid memory. |
LONG CgiFileOpen (struct CgiFile_t ** fileInfo,
BYTE * filePath, LONG fileAccess)
This function opens any logical files and associates them
with memory buffer management. For example, when your
program calls CgiFileOpen to open a disk file, the function
allocates the memory buffer management data structure and
reads the entire disk file into the logical memory file. After
this operation, the current position of the logical memory file
will be set as specified in the fileAccess parameter.
The logical files can apply to disk file, socket.
Parameters
- fileInfo
- [I/O] Pointer to the fileInfo data structure.
- filePath
- [IN] Pointer to the full file path. If this value is NULL, no
physical file is associated (that is, the file resides in memory
only). In this case, only the memory buffer management data
structure is allocated.
- fileAccess
- [IN] Access mode of the file. You can specify any one of
the following values:
- CgiFileC_ReadOnly
- The access mode is to permit the disk file to be read only,
the share access mode is to permit both read/write access to
the disk file, and the disk file is immediately closed once this
operation is completed. The current file position will point to
the beginning of the logical memory file.
- CgiFileC_ReadWrite
- The access mode is to permit the disk file to be both read
and written, the share access mode is to permit read access
and prevent write access to the disk file. This value causes
the disk file to remain open until the CgiFileClose function is
issued. The current file position points to the beginning of the
logical memory file. CgiFileC_Truncate causes the disk file
to be truncated to contain no data when the file exists. This
function has no effect when the file does not exist. The disk
file will remain open until the CgiFileClose function is issued.
The access mode is to permit access and prevent write
access to the disk file. The current file position points to the
beginning of the logical memory file.
- CgiFileC_Exclusive
- The access mode is to permit the disk file to be both read
and written, the share access mode is to deny read and write
access to the disk file. The disk file will remain open until the
CgiFileClose function is issued. The current file position
points to the beginning of the logical memory file.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_FileOpenFail | Failed to open logical file. |
| CSSME_TextPtrInvalid | The returned address of CgiFile (fileInfo) or the pointer to the logical
file does not point to valid memory. |
LONG CgiFileRead (struct CgiFile_t * fileInfo,
LONG * bufLen, BYTE * bufPtr)
This function reads data from the logical memory file into the
specified output data buffer. As data is read from the
memory file, the current file position is advanced. The
current file position can be set using the CgiFileSeek
function.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- bufLen
- [I/O] On input, this parameter contains the length of read
buffer. On output, this parameter returns the number of
bytes written to output buffer.
- bufPtr
- [I] Pointer to the buffer to receive data.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo), or the returned address of buffer
length (bufLen), or the pointer to the buffer (bufPtr) does not point to
valid memory. |
LONG CgiFileSeek (struct CgiFile_t * fileInfo,
LONG seekOptions, LONG * seekOffset)
This function sets the current read/write memory file
position.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- seekOptions
- [IN] The seek starting point. This parameter can contain any
one of the following values:
- CgiFileC_SeekStart
- The new file position is computed relative to the start of the
logical memory file.
- CgiFileC_SeekCurrent
- The new file position is computed relative to the current start
of the logical memory file.
- CgiFileC_SeekEnd
- The new file position is computed relative to the end of the
logical memory file.
- seekOffset
- [I/O] On input, this parameter specifies the relative offset
from the seekOptions. On output, this parameter will specify
the new logical offset of the current read/write memory
position.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidSeekOptions | The seekOptions parameter is invalid. |
| CgiE_InvalidOffset | The seekOffset parameter is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the address of seekOffset
(seekOffset) does not point to valid memory. |
LONG CgiFileStrCat (struct CgiFile_t * fileInfo,
BYTE * appendStr)
Append the specified null-terminated string, appendStr, to
the end of the memory file. When this operation is
completed, the logical memory current file position is the
new end of the file. Use the CgiFileSeek function to reset the
current file position.
Parameters
- fileInfo
- [IN] Pointer to the CgiFile info data structure.
- appendStr
- [IN] Pointer to the string to be appended.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to append string buffer
(appendStr) does not point to valid memory. |
LONG CgiFileStrDelete (struct CgiFile_t *
fileInfo, LONG * delOffset, BYTE * delStr)
Delete data starting at delOffset in the memory file with
the length specified by delStr. After this operation, the
current file position points to the first byte past the last byte
deleted.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- delOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical delete offset. Otherwise, the
file is repositioned as specified. On output, if the pointer is
not NULL, the logical offset of the first byte following the
delete location is returned.
- delStr
- [IN] Pointer to the string to be deleted.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidOffset | The delOffset parameter is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) does not point to valid memory. |
LONG CgiFileStrFind (struct CgiFile_t *
fileInfo, LONG * searchOffset, BYTE *
searchStr)
Searches from the searchOffset of the logical memory file
for the string defined in the searchStr parameter.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- SearchOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical search offset. Otherwise, this
parameter contains the logical offset of the first byte of
search data in the logical memory file and the current file
position is updated to be the first byte of the matching search
data. On output, if the pointer is not NULL, the logical offset
of the found location is returned. If the data was not found,
this parameter contains -1 and the current file position is
NOT changed.
- SearchStr
- [IN] Pointer to the string to be searched.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidOffset | The searchOffset parameter is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo), or the address of searchOffset
(searchOffset), or the pointer to the search string (searchStr) does
not point to valid memory. |
LONG CgiFileStrInsert (struct CgiFile_t *
fileInfo, LONG * insertOffset, BYTE * insertStr)
Inserts a string into the logical memory file. After this
operation, the current file position will point to the offset of
next byte of the insert string in the logical memory file.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- InsertOffset
- [I/O] On input, if the pointer is NULL, the current file
position is used as the logical insert offset. Otherwise, the file
is repositioned as specified. On output, if the pointer is not
NULL, the logical offset of the first byte following the
inserted data will be returned.
- InsertStr
- [IN] Pointer to the string to be inserted.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_InvalidOffset | The insertOffset parameter is invalid. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to the insert string
(insertData) does not point to valid memory. |
LONG CgiFileStrmRead (struct CgiFile_t *
fileInfo, struct Cgi_t * cgiInfo, LONG *
bytesRead)
This function reads input data from the associated client
session socket into the logical memory file. All data is
logically appended to the memory file; therefore, the current
file position is advanced as new data is added to the file.
This operation continues until there is no more data in the input
socket to read for the current read request. However, since data
arriving at the socket is an asynchronous event, there may be more
data at a later time.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- CgiInfo
- [IN} Pointer to the cgiInfo data structure.
- bytesRead
- [I/O] Number of bytes read from the socket.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (fileInfo) or the pointer to CgiFile (fileInfo) does
not point to valid memory. |
LONG CgiFileStrmWrite (struct CgiFile_t *
fileInfo, struct Cgi_t * cgiInfo, LONG *
bytesWritten)
This function writes data from the logical memory file to a
socket associated with the current client/server session
defined by Cgi_t. This operation advances the logical
memory current file position.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- bytesWritten
- [OUT] Number of bytes written from the socket.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (fileInfo) or the pointer to CgiFile (fileInfo) does
not point to valid memory. |
LONG CgiFileWrite (struct CgiFile_t * fileInfo,
LONG bufLen, BYTE * bufPtr)
This function writes data from buffer to the current write
position in the logical memory file.
This operation can overwrite the logical memory file. This operation
advances the logical memory current file position.
Parameters
- fileInfo
- [IN] Pointer to the fileInfo data structure.
- bufLen
- [IN] Number of bytes to write.
- bufPtr
- [IN] Pointer to a buffer to write data.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to the buffer (bufPtr)
does not point to valid memory. |
Generating Log File Entries
The functions in this class generate entries for the different log files.
LONG CgiLogAccess (struct Cgi_t * cgiInfo,
BYTE * fmtStr, ...)
This function generates an entry in the access log file. The
entry, written in the common log file format, contains the
printf string provided in the fmtStr parameter.
For example, issuing the following
command:CgiLogAccess(cgiInfo, " This is a test!");generates the
following entry in the access log file: 130.57.5.215 - -
[20/Feb/1996:13:55:00 -0800] "GET /lcgi/cgisdk.nlm? HTTP/1.0"
- 0 This is a test!
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- fmtStr
- [IN] printf style format string.
...
[IN] Variable arguments.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to the format string
(fmtStr) does not point to valid memory. |
LONG CgiLogError (struct Cgi_t * cgiInfo,
BYTE * fmtStr, ...)
This function generates an entry in the error log file. The
entry contains the printf string provided in the fmtStr
parameter.
For example, issuing the following command:
CgiLogError(cgiInfo, " This is a test!");
generates the following entry in the error log file:
[Tue Feb 20 13:55:00 1996] This is a test!
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data struct.
- fmtStr
- [IN] printf style format string.
...
[IN] Variable arguments.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to CgiFile (fileInfo) or the pointer to the format string
(fmtStr) does not point to valid memory. |
Allocating Memory
The functions in this class allocate and deallocate memory. Since the LCGI NLM runs under the
context of the Web Server thread, all memory allocations are owned by the Web Server. These
functions use the internal memory manager, which provides garbage collection and displays any
unreleased memory/resources to the console. This allows you to easily free all memory to decrease
memory fragmentation.
LONG CgiMemFree (char ** memPtr)
This function deallocates and zeros the caller's pointer to
memory. If the memory was not allocated through the
CgiMemGet routine, it is returned through the OS free
routine.
TheCgiMemGet and CgiMemFree functions use the underlying
Web Server's memory management subsystem to reduce the
amount of memory fragmentation that typically occurs on the
NetWare 4.1x server when memory is constantly being allocated
and freed.
Parameters
- memPtr
- [IN] Points to memory to be freed. This parameter is set to
NULL on return.
Return Value:
| Value | Meaning |
| SUCCESS | Memory was returned to the managed pool. |
| CgiE_InvalidCgiMemFree | Memory was returned to the NetWare OS memory pool. This
return value can be used to help identify memory that was not
allocated through the CGI memory manager. |
LONG CgiMemGet (void ** memPtr, size_t
memSize)
This function allocates a requested memory buffer. This
function is non-blocking in that if the requested memory is
not immediately available, no memory is returned to the
caller.
The CgiMemGet and CgiMemFree functions use the underlying
Web Server's memory management subsystem to reduce the
amount of memory fragmentation that typically occurs on the
NetWare 4.1x server when memory is constantly being allocated
and freed.
Parameters
- memPtr
- [OUT] Points to the start of the newly allocated memory.
- memSize
- [IN] Specifies the size (in bytes) of the memory block to be
allocated.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The returned address of newly allocated memory (memPtr) does not
point to valid memory. |
Using NetWare Locking
The functions in this class lock and unlock the threads for an LCGI NLM to access any of its
global resources when running on either an SMP machine or a single processor machine. Each
NLM gets one mutex semaphore structure to use for locking threads. If more semaphores are
required, they need to be created at a lower level.
LONG CgiMutexLock (LONG cgiHandle)
This function locks all threads running in the same LCGI
NLM from running simultaneously on either an SMP
machine or a single processor machine. Any resources that
are global to threads executing in an LCGI NLM should call
the Lock and Unlock functions whenever accessing or
modifying a global resource of that LCGI NLM.
Parameters
- cgiHandle
- [IN] The extension module handle that was returned by the
LCGI registration routine.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CeSmpE_BadSemaphore | The caller has attempted an operation on an invalid semaphore. |
LONG CgiMutexUnlock (LONG cgiHandle)
This function unlocks all threads running in the same LCGI
NLM from running simultaneously on either an SMP
machine or a single processor machine. Any resources that
are global to threads executing in an LCGI NLM should call
the Lock and Unlock functions whenever accessing or
modifying a global resource.
Parameters
- cgiHandle
- [IN] The extension module handle that was returned by the
Cgi registration routine.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CeSmpE_BadSemaphore | The caller has attempted an operation on an invalid semaphore. |
Using the CGI Stream Interface
The functions in this class are for reading data from and writing data to the CGI stream interface.
LONG CgiStrDup (BYTE ** retStr, BYTE *
dupStr)
This function is equivalent to the ANSI strdup function
except that it allocates memory from the local memory
manager function, CgiMemGet. It is the responsibility of the
caller to free the retStr memory using the corresponding
CgiMemFree function.
Parameters
- retStr
- [I/O] Returned as duplicated string (memory is allocated).
- dupStr
- [IN] Pointer to a null terminated string to be duplicated.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CEE_NoMemory | Unable to allocate requested dynamic memory. |
| CSSME_TextPtrInvalid | The address of retStr or the pointer to the string (dupStr) does not
point to valid memory. |
LONG CgiStrmCharGet (struct Cgi_t * cgiInfo,
LONG * getChar)
This function returns a single character from the socket
input buffer.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- getChar
- [I/O] The character in the low half, or EOF if there are
none.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_EndOfFile | End Of File has been returned for the logical network connection. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the address of getchar does not point
to valid memory. |
LONG CgiStrmCharPut (struct Cgi_t * cgiInfo,
LONG putChar)
This function writes a single character to the socket. Flush
first if necessary.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- putChar
- [IN] The character to write (in low byte).
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) does not point to valid memory. |
LONG CgiStrmCharUnGet (struct Cgi_t *
cgiInfo, int unGetChar)
Returns the most recently read character to the buffer by
resetting the buffer pointers. Also verifies this value by
comparing the character returned with that location in the
buffer. Fails if the characters do not match.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- unGetChar
- [IN] The character to `unget'.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_UnGetCharNotMatched | A call to CgistrmCharUnGet failed because the character was
not matched. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) does not point to valid memory. |
LONG CgiStrmDataGet (struct Cgi_t * cgiInfo,
LONG * bufLen, BYTE * bufPtr)
Get data to buffer from socket's input buffer.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- bufLen
- [I/O] On input, specifies the length of bufPtr. On output,
specifies the number of bytes actually retrieved.
- bufPtr
- [I/O] Buffer to receive data.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the pointer to the buffer length
(bufLen), or the pointer to buffer (bufPtr) does not point to valid
memory. |
LONG CgiStrmDataPut (struct Cgi_t * cgiInfo,
LONG bufLen, BYTE * bufPtr)
This function writes data to a socket. Flush as many times as
necessary to copy the entire data.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- bufLen
- [I/O] Specifies the length of bufPtr.
- bufPtr
- [IN] Points to the character data to be written.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the address of retSize, or the pointer
to buffer (bufPtr), does not point to valid memory. |
LONG CgiStrmFileSend (struct Cgi_t * cgiInfo,
BYTE * filePath)
Open the disk file(specified by filePath) in binary mode, send
every byte to the socket"s output buffer until completion,
then close the disk file.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo data structure.
- filePath
- [IN] Full path of the file to send to the socket's output
buffer.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the pointer to the full path of the file
(filePath) does not point to valid memory. |
LONG CgiStrmFlush (struct Cgi_t * cgiInfo)
Sends the current contents of the output buffer and resets
the output buffer pointer to the beginning. This operation has
no effect for parsed headers.
Parameters
- cgiInfo
- [IN] The caller's cgiInfo structure.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) does not point to valid memory. |
LONG CgiStrmPrintf (struct Cgi * cgiInfo,
LONG * fmtLen, BYTE * fmtStr, ...)
Sends formatted output to the socket's output buffer. Flush
as many times as necessary to accomplish this task.
Parameters
- cgiInfo
- [IN] The caller's cgiInfo structure.
- fmtLen
- [OUT] The length of the format specifier string.
- fmtStr
- [IN] A standard printf format specifier string.
...
[IN] Variable based on the format specifier string.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the address of the format's length
(fmtLen), or the pointer to the format string (fmtStr) does not point to
valid memory. |
LONG CgiStrmStdHdrSend (struct Cgi_t *
cgiInfo, BYTE * contentType, int
contentLength)
Sends a standard header containing the information specified
in the parameters, that is, 200 OK, server version,
content-type, and content-length.
This function DOES NOT send a blank line following the header
information. Your program must send an explicit "\r\n" to terminate
the HTTP header before sending any HTML data.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo structure.
- contentType
- [IN] Content type string. For example, "text/html".
- contentLength
- [IN] Content length, or -1 for "don't send one".
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the pointer to the content type string
(contentType) does not point to valid memory. |
LONG CgiStrmStrGet (struct Cgi_t * cgiInfo,
LONG * bufLen, BYTE * bufPtr)
Get a string to buffer from a socket's output buffer. The
delimiters for the string are the null character (\0), newline
character (\n), carriage return character (\r), and end of file.
This function appends the return string with a null character.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo structure.
- bufLen
- [IN] Specifies the length of bufPtr.
- bufPtr
- [IN] Pointer to the string to be written.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the address of retSize, or the pointer
to the buffer (bufPtr) does not point to valid memory. |
| CgiE_BufferLength | The calling routine has specified an invalid buffer length. |
LONG CgiStrmStrPut (struct Cgi_t * cgiInfo,
LONG bufLen, BYTE * bufPtr)
This function writes a string to a socket's output buffer.
Flush as many times as necessary to copy the entire string.
Parameters
- cgiInfo
- [IN] Pointer to the cgiInfo structure.
- bufLen
- [IN] Specifies the length of bufPtr.
- bufPtr
- [IN] Pointer to the string to be written.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to Cgi (cgiInfo), or the address of retSize, or the pointer
to the buffer (bufPtr) does not point to valid memory. |
Manipulating the URL
The functions in this class manipulate the URL.
LONG CgiUrlEscape (BYTE * url, BYTE **
escUrl)
This function converts the url parameter to its HTTP
escaped equivalent and embeds the escape codes in the
destination string in place of the original characters.
This routine allocates memory for the escaped string and copies the
source to the destination with changes. This process is necessary
because the escaping process expands the source string. The buffer
must be large enough to hold the characters embedded in the
escaped string. It is the responsibility of the caller to free this
memory.
Parameters
- url
- [IN] Pointer to string to be HTTP escaped.
- escUrl
- [OUT] Allocated memory for escaped URL.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CSSME_TextPtrInvalid | The pointer to url does not point to valid memory. |
LONG CgiUrlUnEscape (BYTE * url)
This function unescapes the URL.
Parameters
- url
- [I/O] On input, specifies the pointer to string URL. On
output, this parameter will specify the unescaped string
URL.
- setUrl
- [IN] New URL to be set.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
Using a Work Pointer
The functions in this class get and set a work pointer. The work pointer is a private information
structure that an LCGI NLM can use to pass data from one LCGI NLM to another, such as during
a request that requires chaining.
LONG CgiWorkPtrGet (struct Cgi_t * cgiInfo,
void ** workPtr)
This function gets the caller's work pointer from the cgiInfo
struct being used by the NLM processing thread. The
workPtr is a private pointer stored in the cgiInfo structure.
LCGI NLMs can set or use this pointer to store any kind of
information. Therefore, it is the responsibility of the caller to
allocate the memory to save the information and to free the
memory when it finishes.
Parameters
- cgiInfo
- [IN] Pointer to the caller's cgiInfo structure. The cgiInfo
structure is the information structure that is passed between
the Web Server and LCGI NLMs.
- workPtr
- [I/O] Caller-defined pointer to set from the cgiInfo structure.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CgiE_NoValueSet | The workPtr field has not been set. |
| CCSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the address of the work pointer
(workPtr) does not point to valid memory. |
LONG CgiWorkPtrSet (struct Cgi_t * cgiInfo,
void * workPtr)
This function sets the caller's work pointer from the cgiInfo
struct being used by the LCGI NLM processing thread. The
workPtr is a private pointer stored in the cgiInfo structure.
LCGI NLMs can set or use this pointer to store any kind of
information.Therefore, it is the responsibility of the caller to
allocate the memory to save the information and to free the
memory when it finishes.
Parameters
- cgiInfo
- [IN] Pointer to caller's cgiInfo structure. The cgiInfo
structure is the information structure that is passed between
the Web Server and LCGI NLMs.
- workPtr
- [I/O] Caller-defined pointer to set from the cgiInfo structure.
Return Value
| Value | Meaning |
| SUCCESS | Successful. |
| CCSME_TextPtrInvalid | The pointer to Cgi (cgiInfo) or the address of the work pointer
(workPtr) does not point to valid memory. |