The RegisterProgram function registers an executable
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 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 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 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 virtual path associated with the program. If
lpszParameters is NULL or a zero-length string, then 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.
The application can obtain a copy of the output from the command by
calling the GetProgramOutput function 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.
m_pServer->RegisterProgram(hServer,
VIRTUAL_HOST_DEFAULT,
HTTP_METHOD_DEFAULT,
_T("/order/invoice"),
_T("%ProgramData%\\MyServer\\Programs\\invoice.exe"),
NULL,
NULL);