ISAPI Extensions

Sambar Server Documentation

ISAPI Extensions

Overview
There are two types of ISAPI extensions: associated and direct execute. An associated ISAPI extension is called when the target document requested has a MIME extension that has been associated with that extension. Perhaps the most well know ISAPI associated extenions is: *.asp = asp.dll; this results in Microsoft's Active Server Page extension (asp.dll) being called for all pages with the .asp file extension. Important: The Sambar Server cannot presently support Active Server Pages due to Microsoft barriers. A direct execute extension is called from the URL, for example: http://localhost/testext.dll would result in the ISAPI extension testext.dll being called directly to respond to the request.

There are numberous requirements for ISAPI extensions including:

Extensions must contain the entry point GetExtensionVersion. At present, the Sambar Server supports version 2.0 (with the exception of asynchronous I/O).
Extensions must contain the entry point HttpExtensionProc, which is called to process the HTTP request that activated the DLL.
Extensions must use the Extension Control Block and the defined Callback Functions.
Extensions must be thread-safe (pre-emptive). This means that access to static or global data in a DLL must be synchronized using semaphores, critical sections, or mutexes.

Associated ISAPI Extensions
The Sambar Server uses a simple "mapping" file to associate document mime types or entire directories with an ISAPI extension for server-side execution. The config/mappings.ini file stores the Sambar Server aliases and associations (Document Aliases, CGI/WinCGI aliases and ISAPI associations). A system administration GUI is provided for specifying the Associated ISAPI Extensions in the following format:

*.cfm = iscf.dll

The above association will result in the ISAPI Extension iscf.dll being called for any Document requested with a file extension ending in .cfm. The ISAPI Extension iscf.dll never appears in the target of a URL. A request like: http://localhost/foobar.cfm results in the ISAPI extension iscf.dll being called to respond to the request for the document /foobar.cfm.

Important: The ISAPI extension iscf.dll in the above example must be found in the bin directory of the Sambar Server or in the path of the user executing the Sambar Server. Optionally, the entire path of the DLL can be specified in the association:

*.cfm = c:\coldfusion\iscf.dll

Once an ISAPI application has been loaded by the Sambar Server, it remains loaded until the server is stopped (or restarted).
Direct Execute ISAPI Extensions
The Sambar is configured to execute any file in the Documents Directory with a .dll file extension as an ISAPI Extension. This configuration field is specified in the ISAPI Extensions configuration parameter found in the config/config.ini file (and operations in the same manner as the CGI Extensions and WinCGI Extensions parameters.)
A direct execute ISAPI extension is always found in the target of a URL. For example: http://localhost/foobar.dll would result in the execution of the ISAPI Extension /foobar.dll to respond to the URL request.
ISAPI Interfaces and Data Structures
All ISAPI interfaces and data structures are defined in include/httpext.h found in the Sambar Server installation directory. When the Sambar Server loads an extension for the first time, it looks for an exported function called GetExtensionVersion, which all extensions must implement. This function indicates the version of the ISAPI specification for which the extension was written. Presently, the Sambar Server only supports Version 2.0 of the ISAPI specification. The following is a sample of how the GetExtensionVersion might be implemented:

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer) { pVer->dwExtensionVersion = MAKELONG(HSE_VERSION_MINOR, HSE_VERSION_MAJOR); lstrcpyn(pVer->lpszExtensionDesc, "Sambar Server Test Extension.", HSE_MAX_EXT_DLL_NAME_LEN); }

The Sambar Server logs the successful loading of the ISAPI extension and prints the extension description to the log/server.log file.
The Sambar Server then calls the HTTPExtensionProc and passes the Extension Control Block (ECB). The ECB generally contains all of the information needed to carry out the client's request. For variables not represented in the ECB, the GetServerVariable API can be used. The Sambar server supports all server variables listed in the ISAPI documentation, as well all Sambar Server and server-side include environment variables. The System Administration forms contain an Environment Variable Report page with all of the Sambar Server variables.
Note: A response of HSE_STATUS_PENDING is not supported by the Sambar Server. The Sambar Server does not support the ISAPI asynchronous I/O features.
For POST operations, the ECB contains the data associated with the POST arguments in the lpbData pointer. This is a null-termianted string. The Sambar Server uses its internal content reading functionality to read all of the content sent with the request into memory. Therefore, the ECB lpbData field will point to a memory block containing the entire content sent (up to 90K). The ECB cbAvailable and cbTotalBytes will always be equal. No ReadClient loops are needed (ReadClient always returns FALSE).
ISAPI extensions use the HSE_REQ_SEND_RESPONSE_HEADER command to respond the HTTP request (Note: if no header is sent, the Sambar Server will emit a default header indicating data follows and specifying the content type as the default MIME type for the Sambar Server text/plain). The following is an example of how to specify a response using the ISAPI interface:

TCHAR lpszBuff[] = "Content-type: text/html\r\n"; DWORD dwSize = sizeof(lpszBuff); pEcb->ServerSupportFunction(hConn, HSE_REQ_SEND_RESPONSE_HEADER, NULL, &dwSize, (LPDWORD)lpszBuff);

Ihe ISAPI extension will use the WriteClient to respond to the user request with content. The content should match the Content-type specified in the response header. The Sambar Server's implementation of WriteClient is buffered. For most ISAs, buffering will significantly improve network throughput by minimizing the number of packets transmitted for a given HTTP response. If the ISA depends on unbuffered I/O to the network, it may not operate as expected.
Lastly, the lpszLogData member of the ECB structure can be used to write debug information in the the Sambar Server log file (log/server.log).
Debugging ISAPI Extensions
The Sambar Server provides limited built-in debugging of ISAPI Extensions. This debugging feature is configurable from the System Administration Server configuration form. The ISAPI Debug parameter can be configured for one of the following:

None: No logging of any kind.
Basic: Log only ISAPI function failures.
Call: Trace all ISAPI function calls.
Full: Detailed trace of each ISAPI call (for developers only).

When Full debugging is enabled, the log/isapi.log file includes detailed usage of the ISAPI interfaces. The following is a sample log file for the testisa.dll (note: this ISA DLL uses few calls):

[06/Feb/1998:09:36:23 -0800] Loading testisa.dll: Sambar Server ISAPI Test extension. [06/Feb/1998:09:36:23 -0800] testisa.dll: Run for 140.172.165.58 [06/Feb/1998:09:36:23 -0800] testisa.dll: ServerFunc() HSE_REQ_SEND_RESPONSE_HEADER '200 OK' [06/Feb/1998:09:36:23 -0800] testisa.dll: Returned HSE_STATUS_SUCCESS

© 1998 Sambar Technologies. All Rights reserved. Terms of use.