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 lpszProgramFile 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 lpszProgramFile
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 lpszParameters 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 lpszParameters is
a NULL pointer, 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.
The application can obtain a copy of the output from the command by
calling the GetProgramOutput method from within an OnExecute
event handler.
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.
// Register a handler for VBScript
pServer->RegisterHandler(hServer,
VIRTUAL_HOST_DEFAULT,
_T("vbs"),
_T("%SystemRoot%\\System32\\cscript.exe"),
_T("/nologo /b \"%1\""),
NULL);