gcgi.html

C/C++语言的CGI接口库

		<span class="codeHeader">gcgiReturnType  gcgiParseEncryptedCookie(char *cookie, unsigned char *key, char **name, char **value)</span><br>
	        Identical to <span class="code">gcgiParseCookie()</span> except you must pass in a <span class="code">key</span>
	        so that the cookie can be decrypted.  You must build with OpenSSL to use this function.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiGenerateKey(unsigned char **key)</span><br>
	        This function will generate a key to use for encrypting and decrypting. You must build with OpenSSL 
	        to use this function.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiWriteKeyToFile(unsigned char *key, char *path)</span><br>
	        This function will write a key to an external file.  While GCGI can generate and use keys for encrypting
	        and decrypting, the calling program has the responsibility to store that key.  This function can help with
	        that task by writing it properly to a file.  You must build with OpenSSL to use this function.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiReadKeyFromFile(char *path, unsigned char **key)</span><br>
	        This function will read a key to an external file.  While GCGI can generate and use keys for encrypting
	        and decrypting, the calling program has the responsibility to store that key.  This function can help with
	        that task by reading it properly from a file.  You must build with OpenSSL to use this function.
	        </p>
	  <p><span class="subsection">HTTP Header Functions</span></p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiSendContentType(char *mimeType, char *name, char *charset, HTTPHeader header)</span><br>
		This function will send a <span class="code">Content-Type</span> header back to the client browser.  
	        This function <b>must</b> be called before any other HTTP header functions.  <span class="code">mimeType</span>
                should be a valid MIME string, such as <span class="code">text/html</span> or <span class="code">image/png</span>.
	        <span class="code">name</span> and <span class="code">charset</span> are optional.  If this is the only HTTP
	        header you are sending then <span class="code">header</span> should be <span class="code">LAST</span>, otherwise 
	        set it according to the next header you are going to send.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiSendContentDisp(MimeDisposition disp, char *filename, HTTPHeader header)</span><br>
	        This function will send a <span class="code">Content-Disposition</span> header.  You <b>must</b> call the
	        <span class="code">gcgiSendContentType()</span> first.  <span class="code">disp</span> should be either
	        <span class="code">inlined</span> or <span class="code">attachment</span> and <span class="code">filename
	        should be a string that you want the client browser to use to save the file as.  If this is the last HTTP
	        header you are sending then <span class="code">header</span> should be <span class="code">LAST</span>, otherwise 
	        set it according to the next header you are going to send.See the 
	        <a href="./fileupload.html">fileupload</a> example on ways to use this.
		</p>
	        <p>
		<span class="codeHeader">gcgiReturnType gcgiSendContentLength(int length, HTTPHeader header)</span><br>
	        This function will send a <span class="code">Content-Length</span> header.  This allows you to specify
	        how much data you are sending (specified in octets) to the client browser.  Useful when dynamically 
	        generating things like images.
	        </p>
	        <p>
		<span class="codeHeader">gcgiResultType gcgiSendCacheControl(char *cache, HTTPHeader header)</span><br>
	        This function allows you to send various cache control directives to the client browser and proxy
	        machines in between the CGI program and the client browser.  See RFC2616 for details on this header
	        (it is included in the <span class="code">doc/</span> directory).  If this is the last HTTP header you are 
	        sending then <span class="code">header</span> should be <span class="code">LAST</span>, otherwise 
	        set it according to the next header you are going to send.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiSendLocation(char *redirectURL)</span><br>
		  This function will tell the client browser to redirect itself to the URL provided in 
	          <span class="code">redirectURL</span>.  This function must not be called with any other HTTP functions.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiSendStatus(int status, char *message)</span><br>
		  This function will send the client browser an HTTP status number and a message to go along with that
	          number.  See RFC2616 for details on this header (it is included in the 
	          <span class="code">doc/</span> directory). This function must not be called with any other HTTP functions.
		</p>

	  <p><span class="subsection">Debugging Functions</span></p>
                <p>
                <span class="codeHeader">gcgiResultType gcgiDebug(char *envpath, char *querypath)</span><br>
                  This function will place GCGI into debug mode.  It will load the environment variables from the 
                  filepath contained in <span class="code">envpath</span>, and will load query data from 
	          <span class="code">querypath</span>.  The environment variables can be captured to a file by calling 
                  <span class="code">gcgiSaveEnvVariables()</span>, the query data file is only needed if you are 
         	  debugging POST queries and you must create it your self.  In the future, GCGI wlil be able to generate it,
	          until then you can use the <span class="codeHeader">gcgiGetInput</span> program included in 
	          the <span class="code">examples/</span> directory to capture it.
                </p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiLoadEnvVariables(char *path)</span><br>
		  This function will load all of the necessary CGI environment variables from a file to facilitate
		  debugging.  Using this factility, CGI programs can be run through a debugger, or from the command line.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiSaveEnvVariables(char *path)</span><br>
		  This function will capture a CGI environment to a file for later use with 
		  <span class="code">gcgiLoadEnvVariables()</span>.		    
		</p>		
		<p>
		<span class="codeHeader">gcgiResultType printQuery(FILE *stream)</span><br>
		  This function will dump a textual representation of the GCGI structures to a file stream.
		</p>		
	    <a name="examples"></a>
	    <span class=section>Examples:</span>
	<p>Their are several examples included in the GCGI tarball that do the following:</p>
	<p>
                <span class="codeHeader">gcgiFormTest</span> -- 
	                        An example of a vanilla CGI program that fetches data from an HTML
                                form. Use this program with the <a href="./formexample.html">formexample.html</a> file.
	</p>
	<p>
                <span class="codeHeader">gcgiFileUploadTest</span> -- 
	                        An example of how to upload files with GCGI.  Use this program
                                with the <a href="./fileupload.html">fileupload.html</a> file.
	</p>
	<p>
                <span class="codeHeader">gcgiCookieTest</span> -- 
	                        An example of how to use regular and encrypted cookies with GCGI.
                                Use this program with the <a href="./cookietest.html">cookietest.html</a> file.
	</p>
	<p>
                <span class="codeHeader">gcgiGetInput</span> -- 
	                        A small utility program that will capture the input to a CGI program.
                                This is useful when debugging with GCGI. Use this program to capture
                                the incoming POST data and use it along with the gcgiDebug() method in GCGI
                                to run a program in a debugger or from the command line. It was used to 
                                capture the POST data files included in the examples directory.
	</p>

	    <a name="debugging"></a>
            <span class=section>Debuging:</span>
            <p>
	    <ol>
		<li>You first need to capture a running CGI environment to a file.  To do this, use the 
		    <span class="code">gcgiSaveEnvVariables(char *path)</span> function.  Either place it into
   	 	    the program you are trying to debug, or create a small program that you invoke form the 
	   	    HTML form and use it to capture the environment.  Something like this will do:
	            <p style="background: #cccccc; font; white-space: pre; font-family: fixed;">
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include "gcgi.h"

int main (int argc, char *argv[], char *envp[]) 
{
  if (initCgi() < 0)
    return -1;
  
  gcgiSaveEnvVariables("./urlencodedenv");

  freeCgi();

  return 0;
}
		    </p></li>
		<li><p>Next you need to capture the CGI query string.  The easiest way to do this is to set your 
		    HTML form to use a GET query. Then, after submitting the form, you can copy the query string 
		    directly from the address input in the web browser or from the environment variables file that
	            is created (use the QUERY_STRING variable).</p><p>If you have a POST query that you want to capture, 
	            use the utility program, <span class="codeHeader">gcgiGetInput</span> included in the 
	            <span class="code">examples/</span> directory.  Set your HTML form to submit its data to this program,
	            which will then output it, unmodified, to a file.</p><p>Here is an example of the environment 
	            variables file that would be created with the GET string added to the QUERY_STRING variable:</p>
<p style="background: #cccccc; font; white-space: pre; font-family: fixed;">
CONTENT_LENGTH=
CONTENT_TYPE=application/x-www-form-urlencoded
GATEWAY_INTERFACE=CGI/1.1
QUERY_STRING=string=some+text&amp;integer=432&amp;double=12.3985
REMOTE_ADDR=192.168.0.2
REQUEST_METHOD=POST
SCRIPT_NAME=/cgi-bin/gcgitest
SERVER_NAME=topeka.shingletowngap.org
SERVER_PORT=80
SERVER_PROTOCOL=HTTP/1.1
SERVER_SOFTWARE=Apache/1.3.9 (Unix)  (SuSE/Linux) mod_perl/1.21
                    </p></li>
		</li>
		<li>Last, add a call to your program before the <span class="code">initCgi()</span> call to
		    <span class="code">gcgiDebug(char *envpath, char *querypath)</span> specifying the two
		    files created above.  If you are testing a GET query using the QUERY_STRING environment
                    varible, then the second file is not necessary and you can just passin a blank string.  
	            However, to test POST queries, or RFC2388
		    queries, you need to specify the second file. GCGI will now read its input from the specified
		    files rather than from the webserver.</li>
		<li>Now, you should be able to run your program through a debugger or directly from the command line.
<p style="background: #cccccc; font; white-space: pre; font-family: fixed;">
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt; 
#include "gcgi.h"   
                    
int main (int argc, char *argv[], char *envp[])  
{                   
  gcgiDebug("./urlencodedenv", "./urlencodedquery");

  if (initCgi() < 0)
    return -1;
  
  /* Insert useful code here */

  freeCgi();

  return 0;
}

</p>
		</li>
		</ol> 	
            </p>
	    <a name="history"></a>
	    <span class=section>History:</span>
	    <p>
		GCGI has been implemented from scratch, cleanroom-style.  However, the API attempts to be close 
		to Thomas Boutell's <a href="http://www.boutell.com/cgic/">CGIC</a> where it makes sense.  
		Unfortunately, CGIC does not provide RFC2388 functionality and CGIC's non-free license prevented 
		extensions to the existing library.  So, GCGI was written to fill this gap.
	    </p>
	    <a name="who"> 	    
            <span class=section>Who:</span>
            <p>
	    GCGI was written by <a href="http://catchen.org/topeka/">Julian Catchen</a>.
	    </p>
	<span class=footer>
        <p>
	  <address><a href="mailto:[e-mail]">Julian M Catchen</a></address>
	    <!-- Created: Sun Aug 26 17:36:17 MST 2001 -->
	    <!-- hhmts start -->
Last modified: Sat Jun 15 19:14:05 MST 2002
<!-- hhmts end -->
	</p>
	</span>
    </div>
  </body>
</html>