SocketTools .NET Edition

HttpServer.RegisterProgram Method (Int32, String, String, String, String)

Register a CGI program for use and associate it with a virtual path on the server.

[Visual Basic]
Overloads Public Function RegisterProgram( _
   ByVal hostId As Integer, _
   ByVal command As String, _
   ByVal program As String, _
   ByVal parameters As String, _
   ByVal directory As String _
) As Boolean
[C#]
public bool RegisterProgram(
   int hostId,
   string command,
   string program,
   string parameters,
   string directory
);

Parameters

hostId
An integer value which identifies the virtual host. A value of zero specifies that the default virtual host should be used.
command
A string which specifies the virtual path to the CGI program. This must be an absolute path, but does not have to specify a pre-existing virtual path or map to the directory structure of the root document directory for the server. The maximum length of the virtual path is 1024 characters.
program
A string which specifies the full path to the CGI program on the local system.
parameters
A 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 an empty string.
directory
An optional string that specifies the current working directory for the program. If this parameter is an empty string, the server will use the root document directory for the virtual host.

Return Value

A boolean value which specifies if the CGI program was registered with the server. A return value of true specifies that the operation was successful. If an error occurs, the method returns false and the application should check the value of the LastError property to determine the cause of the failure

Remarks

The RegisterProgram method registers a CGI program and associates it with a virtual path. When the client issues a GET or POST command specifying the virtual path associated with the program, the program will be executed and the output return to the client.

The program 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 virtual paths that reference the same executable file. The only requirement is that the virtual path 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 program 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 virtual path associated with the program. If this argument is omitted, no additional parameters are passed to the program.

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.

See Also

HttpServer Class | SocketTools Namespace | HttpServer.RegisterProgram Overload List