RegisterHandler Method  
 

Register a CGI program for use and associate it with a file name extension.

Syntax

object.RegisterHandler( HostId, FileExtension, ProgramFile, [Parameters], [Directory] )

Parameters

HostId
An integer value which identifies the virtual host. A value of zero specifies that the default virtual host should be used.
FileExtension
A string which specifies the file name extension that is associated with the CGI program.
ProgramFile
A string which specifies the full path to the CGI program on the local system.
Parameters
An optional string that specifies additional parameters for the program. This value will be passed to the program as command line arguments. If the CGI program does not require any command line parameters, this parameter may be omitted.
Directory
An optional string that specifies the current working directory for the program. If this parameter is omitted, the server will use the root document directory for the virtual host.

Return Value

A value of zero is returned if the program was registered successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

Remarks

The RegisterHandler method registers an executable CGI program and associates it with a file name extension. When the client issues a GET or POST command that specifies a file with that extension, the program will be executed and the output return to the client.

The ProgramFile string specifies file name of the CGI program. You should not install any executable programs in the server root directory or its subdirectories. A client should never have the ability to directly access the executable file itself. It is permitted to have multiple file name extensions that reference the same program. The only requirement is that the extension be unique for the given host. The program name may contain environment variables surrounded by % symbols. For example, %ProgramFiles% would be expanded to the C:\Program Files folder.

It is important to note that the program specified by ProgramFile must be an executable file, not a script or batch file. If the program name does not contain a directory path, then the standard Windows pathing rules will be used when searching for an executable file that matches the given name. It is recommended that you always provide a full path to the executable file.

The Parameters string can specify additional command line parameters that should be passed to the CGI program as arguments. This string can also contain a placeholder named "%1" that will be replaced by the full path to the local script filename. If no placeholder is included in the parameters, or the Parameters argument is omitted, the script file name will be passed to the program as its only argument.

The executable program that is registered using this program must be a console application that conforms to the CGI/1.1 specification defined in RFC 3875. Request data submitted by the client as part of a POST will be provided to the program as standard input. The output from the program must be written to standard output. The first lines of output from the program should be any response headers, followed by an empty line. Each line should be terminated with a carriage-return and linefeed (CRLF) sequence. If the CGI program outputs additional data to be processed by the client, it should provide Content-Type and Content-Length response headers.

When developing a CGI program, it is important to take into consideration the environment that it will be executing in. The program will be started as a child process of the server application, and will inherit the same privileges. This means that it will typically have access to the boot drive, the Windows folders and the system registry. CGI programs must ensure that all query parameters and request data submitted by the client have been validated.

If the server is running on a system with User Account Control (UAC) enabled and does not have elevated privileges, do not register a program that requires elevated privileges or has a manifest that specifies the requestedExecutionLevel as requiring administrative privileges.

Example

// Register a handler for VBScript
HttpServer1.RegisterHandler httpHostDefault, "vbs", "%SystemRoot%\System32\cscript.exe", "/nologo /b ""%1"""

See Also

RegisterProgram Method, OnCommand Event, OnExecute Event