ch25.htm

CGI programming is the hottest stuff to look out for in this book

function. If the server calls out to that function, and nobody
answers, it knows that it's not a usable function. Therefore,
the attempt to load the DLL into memory will fail. If, on the
other hand, the function is there, then it will let the server
know what version of the API it conforms to. Microsoft's recommended
implementation of a <TT><FONT FACE="Courier">GetExtensionVersion()</FONT></TT>
definition is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO&nbsp;&nbsp;*version
)<BR>
&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;version-&gt;dwExtensionVersion = MAKELONG(HSE_VERSION_MAJOR,
HSE_VERSION_MINOR);<BR>
&nbsp;&nbsp;&nbsp;lstrcpyn( version-&gt;lpszExtensionDesc, &quot;This
is a sample Extension&quot;,<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
HSE_MAX_EXT_DLL_NAME_LEN);<BR>
&nbsp;&nbsp;&nbsp;return TRUE;<BR>
 }</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">GetExtensionVersion()</FONT></TT>
entry point is really just a way for the server to ensure that
the DLL is conforming to the specification that the server itself
conforms to. It could be that the server or function is too old
(or too new), and so they wouldn't work well together. It's also
possible that future changes will need to know past versions to
accommodate for special changes, or use it for some other compatibility
purpose.
<P>
The actual startup of the function occurs at the <TT><FONT FACE="Courier">HttpExtensionProc()</FONT></TT>
entry point. Similar to the <TT><FONT FACE="Courier">main()</FONT></TT>
function declaration in a standard C program, it accepts data
inside an Extension Control Block. This block is made available
to the function to figure out what to do with the incoming data
before composing a response. Here is the declaration for the <TT><FONT FACE="Courier">HttpExtensionProc()</FONT></TT>
entry point:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">DWORD WINAPI HttpExtensionProc( LPEXTENSION_CONTROL_BLOCK
*lpEcb);</FONT></TT>
</BLOCKQUOTE>
<P>
Whatever happens, you can't keep the client waiting; you have
to tell them something. In addition, it has to be something that
the server understands and can properly deal with. To properly
create a response, the ISA can call on either the <TT><FONT FACE="Courier">ServerSupportFunction()</FONT></TT>
or the <TT><FONT FACE="Courier">WriteClient()</FONT></TT> function
(These functions are defined and explained in &quot;Callback Functions.&quot;).
Within that response, it will want to return one of the valid
return values shown in Table 25.1.<P>
<CENTER><B><FONT SIZE=2>Table 25.1. Acceptable return values for
an ISA application.</FONT></B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><I>Return Value</I></TD><TD WIDTH=348><I>Meaning</I>
</TD></TR>
<TR><TD WIDTH=229><TT><FONT FACE="Courier">HSE_STATUS_SUccESS</FONT></TT>
</TD><TD WIDTH=348>The ISA successfully completed its task, and the server can disconnect and clean up.
</TD></TR>
<TR><TD WIDTH=229><TT><FONT FACE="Courier">HSE_STATUS_SUccESS_<BR>AND_KEEP_CONN</FONT></TT>
</TD><TD WIDTH=348>The ISA successfully completed its task, but the server shouldn't disconnect just yet, if it supports persistent connections. The application hopes it will wait for another HTTP request.
</TD></TR>
<TR><TD WIDTH=229><TT><FONT FACE="Courier">HSE_STATUS_PENDING</FONT></TT>
</TD><TD WIDTH=348>The ISA is still working and will let the server know when it's done by sending an <TT><FONT FACE="Courier">HSE_REQ_DONE_WITH_SESSION</FONT></TT> message through the <TT><FONT FACE="Courier">ServerSupportFunction</FONT></TT> call.
</TD></TR>
<TR><TD WIDTH=229><TT><FONT FACE="Courier">HSE_STATUS_ERROR</FONT></TT>
</TD><TD WIDTH=348>Whoops, something has gone wrong in the ISA. The server should end the connection and free up space.
</TD></TR>
</TABLE></CENTER>
<P>
<P>
All of these extension processes have to interact with something
to get their data, and, as shown before, there's a group of intermediaries
called Extension Control Blocks (ECBs) that handle that particular
duty. They're nothing more than a C structure that is designed
to hold specific blocks of data and allow a few functions to make
use of that data. Here is the setup of an ECB:<BR>
<HR>
<BLOCKQUOTE>
<B>Listing 25.1. Extension Control Block structure.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">// To be passed to extension procedure
on a new request<BR>
//<BR>
typedef struct _EXTENSION_CONTROL_BLOCK {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;cbSize;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Size
of this struct<BR>
&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;dwVersion;&nbsp;&nbsp;&nbsp;&nbsp;//Version
info for this spec<BR>
&nbsp;&nbsp;&nbsp;&nbsp;HCONN&nbsp;&nbsp;&nbsp;&nbsp;ConnID;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Connection
Handle/ContextNumber(don't modify!)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;dwHttpStatusCode;&nbsp;&nbsp;&nbsp;&nbsp;//Http
Status code for request<BR>
&nbsp;&nbsp;&nbsp;&nbsp;chAR&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;lpszLogData[HSE_LOG_BUFFER_LEN];
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//Log
info for this specific&nbsp;&nbsp;request (null terminated)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszMethod;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//
REQUEST_METHOD<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszQueryString;&nbsp;&nbsp;&nbsp;&nbsp;//
QUERY_STRING<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszPathInfo;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//
PATH_INFO<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszPathTranslated;&nbsp;&nbsp;&nbsp;&nbsp;//
PATH_TRANSLATED<BR>
&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;cbTotalBytes;&nbsp;&nbsp;&nbsp;&nbsp;//
Total Bytes from&nbsp;&nbsp;&nbsp;&nbsp;client<BR>
&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;cbAvailable;&nbsp;&nbsp;&nbsp;&nbsp;//
Available Bytes<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPBYTE&nbsp;&nbsp;&nbsp;&nbsp;lpbData;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//
Pointer to client Data (cbAvailable bytes worth)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszContentType;&nbsp;&nbsp;&nbsp;&nbsp;//
Client Data Content&nbsp;&nbsp;Type<BR>
&nbsp;&nbsp;&nbsp;&nbsp;BOOL&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;WINAPI
* GetServerVariable)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;&nbsp;&nbsp;HCONN&nbsp;&nbsp;&nbsp;&nbsp;ConnID,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPSTR&nbsp;&nbsp;&nbsp;&nbsp;lpszVariableName,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPVOID&nbsp;&nbsp;&nbsp;&nbsp;lpvBuffer,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPDWORD&nbsp;&nbsp;&nbsp;&nbsp;lpdwSize);
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;BOOL&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;WINAPI
* WriteClient)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;&nbsp;&nbsp;HCONN&nbsp;&nbsp;&nbsp;&nbsp;ConnID,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPVOID&nbsp;&nbsp;&nbsp;&nbsp;Buffer,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPDWORD&nbsp;&nbsp;&nbsp;&nbsp;lpdwBytes,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;dwReserved);
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;BOOL&nbsp;&nbsp;&nbsp;&nbsp; ( WINAPI
* ReadClient)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;&nbsp;&nbsp;HCONN&nbsp;&nbsp;&nbsp;&nbsp;ConnID,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPVOID&nbsp;&nbsp;&nbsp;&nbsp;lpvBuffer,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPDWORD&nbsp;&nbsp;&nbsp;&nbsp;lpdwSize);
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;BOOL&nbsp;&nbsp;&nbsp;&nbsp; ( WINAPI
* ServerSupportFunction)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;&nbsp;&nbsp;&nbsp;HCONN&nbsp;&nbsp;&nbsp;&nbsp;ConnID,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DWORD&nbsp;&nbsp;&nbsp;&nbsp;dwHSERRequest,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPVOID&nbsp;&nbsp;&nbsp;&nbsp;lpvBuffer,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPDWORD&nbsp;&nbsp;&nbsp;&nbsp;lpdwSize,
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LPDWORD&nbsp;&nbsp;&nbsp;&nbsp;lpdwDataType);
<BR>
}</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
Table 25.2 goes into detail about each individual component of
an Extension Control Block.<P>
<CENTER><B><FONT SIZE=2>Table 25.2. Explanation of fields in the
Extension Control Block.</FONT></B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><I>Field</I></TD><TD WIDTH=115><CENTER><I>Data Direction</I>
</TD><TD WIDTH=279><I>Comments</I></TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">cbSize</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>The size of the structure itself (shouldn't be changed).
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">dwVersion</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Version information of this specification. The form for this information is <TT><FONT FACE="Courier">HIWORD</FONT></TT> for major version number, and <TT><FONT FACE="Courier">LOWORD</FONT></TT> for minor 
version number.
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">ConnID</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>A connection handle uniquely assigned by the server (DO NOT chANGE).
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">dwHttpStatusCode</FONT></TT>
</TD><TD WIDTH=115><CENTER>OU </TD><TD WIDTH=279>The status of the current transaction once completed.
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszLogData</FONT></TT>
</TD><TD WIDTH=115><CENTER>OU </TD><TD WIDTH=279>Contains a null-terminated string for log information of the size (<TT><FONT FACE="Courier">HSE_LOG_BUFFER_LEN</FONT></TT>).
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszMethod</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">REQUEST_METHOD.</FONT></TT>
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszQueryString</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">QUERY_STRING.</FONT></TT>
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszPathInfo</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">PATH_INFO.</FONT></TT>
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszPathTranslated</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">PATH_TRANSLATED</FONT></TT>.
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">cbTotalBytes</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>.
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">cbAvailable</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Available number of bytes (out of <TT><FONT FACE="Courier">cbTotalBytes</FONT></TT>) in the <TT><FONT FACE="Courier">lpbData</FONT></TT> buffer. See the explanation of the Data Buffer that follows this table.

</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpbData</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Pointer to a buffer, of size <TT><FONT FACE="Courier">cbAvailable</FONT></TT>, which holds the client data.
</TD></TR>
<TR><TD WIDTH=196><TT><FONT FACE="Courier">lpszContentType</FONT></TT>
</TD><TD WIDTH=115><CENTER>IN</TD><TD WIDTH=279>Equivalent of the environment variable <TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT>.
</TD></TR>
</TABLE></CENTER>
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
For items that are referred to as &quot;Equivalent of the environment variable...,&quot; a more detailed explanation of the particular environment variables can be found in this chapter in Table 25.6, &quot;Variable Names and Purposes,&quot; and also in <A 
HREF="ch3.htm" >Chapter 3</A>, &quot;Crash Course in CGI.&quot;
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H4>The Data Buffer</H4>
<P>
Sometimes there's a lot of information sent to a program, and
sometimes there's not. By default, <TT><FONT FACE="Courier">lpbData</FONT></TT>
will hold a 48K chunk of data from the client. If <TT><FONT FACE="Courier">cbTotalBytes</FONT></TT>
(the number of bytes sent by the client) is equal to <TT><FONT FACE="Courier">cbAvailable</FONT></TT>,
then the program is telling you that all the information that
was sent is available within the <TT><FONT FACE="Courier">lpbData</FONT></TT>
buffer. If <TT><FONT FACE="Courier">cbTotalBytes</FONT></TT> is