gcgi.html

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

		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchIntegerNext(char *field, int *ret, int defaultRet)</span><br>
		  This function is identical to <span class="code">gcgiFetchInteger()</span> except that if there are 
		  multiple form elements of the same name, this function will return succeeding values if it is called
		  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
		  call, it would return the second instance, etc.  Once all of the values have been iterated through, 
		  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started 
	          over by calling <span class="code">gcgiResetMultipleField()</span>.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchDouble(char *field, double *ret, double defaultRet)</span><br>
		  This function returns a double in the <span class="code">ret</span> parameter for the field specified
		  in the HTML form by <span class="code">field</span>.  Upon success, <span class="code">GCGISUCCESS</span>
		  is returned, and if the field is not present, then <span class="code">ret</span> contains the value 
		  given in <span class="code">defaultRet</span> and <span class="code">GCGIFIELDNOTFOUND</span> is returned.
		  If there is more than one form field of the same name, this funtion will always return the first 
		  value submitted by the browser.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchDoubleNext(char *field, double *ret, double defaultRet)</span><br>
		  This function is identical to <span class="code">gcgiFetchDouble()</span> except that if there are 
		  multiple form elements of the same name, this function will return succeeding values if it is called
		  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
		  call, it would return the second instance, etc.  Once all of the values have been iterated through, 
		  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started 
	          over by calling <span class="code">gcgiResetMultipleField()</span>.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchString(char *field, char *ret, int max)</span><br>
	          This function returns a Null-terminated string in the <span class="code">ret</span> parameter for the 
	          field specified in the HTML form by <span class="code">field</span>. If the input is more than 
	          <span class="code">max</span> characters long, then the string will be truncated.  
	          Upon success, <span class="code">GCGISUCCESS</span> is returned, and if the field is not present, then 
	          <span class="code">GCGIFIELDNOTFOUND</span> is returned.
		  If there is more than one form field of the same name, this funtion will always return the first 
		  value submitted by the browser.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchStringNext(char *field, char *ret, int max)</span><br>
		  This function is identical to <span class="code">gcgiFetchString()</span> except that if there are 
		  multiple form elements of the same name, this function will return succeeding values if it is called
		  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
		  call, it would return the second instance, etc.  Once all of the values have been iterated through, 
		  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started 
	          over by calling <span class="code">gcgiResetMultipleField()</span>.	     
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchStringNoNewLines(char *field, char *ret, int max)</span><br>
	          This function is identical to <span class="code">gcgiFetchString()</span> except that newlines are
	          stripped out of the input and replaced with a space.  The function will remove either 
	          "<span class="code">\r\n</span>" or "<span class="code">\n</span>" sequences.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchStringNoNewLinesNext(char *field, char *ret, int max)</span><br>
      	          This function is identical to <span class="code">gcgiFetchStringNext()</span> except that newlines are
	          stripped out of the input and replaced with a space.  The function will remove either 
	          "<span class="code">\r\n</span>" or "<span class="code">\n</span>" sequences.
		</p>
		<p>
	        <span class="codeHeader">gcgiResultType gcgiFetchData(char *field, char *ret, int max, MimeType *type, char **subtype, MimeEncoding *encoding, char **filename, int *truncated)</span><br>
		  This function will return a block of data into the <span class="code">ret</span> parameter.
		  It is useful for form elements, such as file uploads, which may contain binary data. If the
		  data is larger than <span class="code">max</span> then it will be truncated to 
		  <span class="code">max</span> bytes. The MIME type, subtype, encoding and filename will be returned if 
                  available. For the subtype and filename parameters, you must pass in a pointer to a character string
		  and you must free these variables when you are done with them.  If the data is not available, they 
                  will be NULL.  If this MIME part was truncated because you set input limits with
		  <span class="code">gcgiSetLimits()</span>, then the truncated flag will be set.
		  Upon success, <span class="code">GCGISUCCESS</span> is 
		  returned, and if the field is not present, then  <span class="code">GCGIFIELDNOTFOUND</span> 
		  is returned.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchDataNext(char *field, char *ret, int max, MimeType *type, char **subtype, MimeEncoding *encoding, char **filename, int *truncated)</span><br>
  		  This function is identical to <span class="code">gcgiFetchData()</span> except that if there are 
		  multiple form elements of the same name, this function will return succeeding values if it is called
		  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
		  call, it would return the second instance, etc.  Once all of the values have been iterated through, 
		  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started 
	          over by calling <span class="code">gcgiResetMultipleField()</span>.	     
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFieldLength(char *field, int *ret)</span><br>
		  This function will return the length of the string of the form element specified by
		  <span class="code">field</span> in the <span class="code">ret</span> parameter. 
		  <span class="code">gcgiFieldLength</span> should only be used for text data.  If you are 
		  trying to figure out how big a field is that is not text, such as an image or other file
		  use <span class="code">gcgiFieldSize()</span> instead.  Upon success, 
		  <span class="code">GCGISUCCESS</span> is returned. If the field is not present, then  
		  <span class="code">GCGIFIELDNOTFOUND</span> is returned.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFieldLengthNext(char *field, int *ret)</span><br>
  		  This function is identical to <span class="code">gcgiFieldLength()</span> except that if there are 
		  multiple form elements of the same name, this function will return succeeding values if it is called
		  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
		  call, it would return the second instance, etc.  Once all of the values have been iterated through, 
		  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started 
	          over by calling <span class="code">gcgiResetMultipleField()</span>.	     
		</p>
                <span class="codeHeader">gcgiResultType gcgiFieldSize(char *field, int *ret)</span><br>
                  This function will return the amount of space needed for the form element specified by
                  <span class="code">field</span> in the <span class="code">ret</span> parameter. If the data
		  you are receiving is binary, such as an image file, this function will return the size of the
		  image as it is stored by GCGI.  Upon success,
                  <span class="code">GCGISUCCESS</span> is returned. If the field is not present, then
                  <span class="code">GCGIFIELDNOTFOUND</span> is returned.
                </p>
                <p>
                <span class="codeHeader">gcgiResultType gcgiFieldSizeNext(char *field, int *ret)</span><br>
                  This function is identical to <span class="code">gcgiFieldLength()</span> except that if there are
                  multiple form elements of the same name, this function will return succeeding values if it is called
                  repeatedly.  So, on the first call it returns the first instance of the form field, on the second
                  call, it would return the second instance, etc.  Once all of the values have been iterated through,
                  the function will return <span class="code">GCGIFIELDNOTFOUND</span>.  The iteration can be started
                  over by calling <span class="code">gcgiResetMultipleField()</span>.
                </p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiNumFormFields(int *ret)</span><br>
		  This function will return the total number of fields submitted by the web browser in the 
		  <span class="code">ret</span> parameter. Upon success, <span class="code">GCGISUCCESS</span> 
		  is returned. If the field is not present, then <span class="code">GCGIFIELDNOTFOUND</span> 
		  is returned.		  
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiNumFields(char *field, int *ret)</span><br>
		  This function will return the number of fields with the name specified in <span class="code">field</span>, 
		  as submitted by the web browser. Upon success, <span class="code">GCGISUCCESS</span> 
		  is returned. If the field is not present, then <span class="code">GCGIFIELDNOTFOUND</span> 
		  is returned.		  
		</p>
		<p>
		<span class="codeHeader">int gcgiFetchCheckbox(char *field, int *ret)</span><br>
		  This function will return a 1 in the <span class="code">ret</span> parameter if the form field,
		  specified by <span class="code">field</span> is checked and 0 otherwise. Upon success, 
		  <span class="code">GCGISUCCESS</span> is returned. If the field is not present, then 
		  <span class="code">GCGIFIELDNOTFOUND</span> is returned.		  
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchMultipleCheckbox(char *field, char **data, int size, int **ret)</span><br>
		  This function fills in the integer array, <span class="code">ret</span> with either a 1 or 0 depending
		  if the corresponding checkbox, as specified by the web browser, was checked.  <span class="code">data</span>
		  must be an array of strings that contains the "value" parameter of the checkboxes as specified in the HTML form.
		  <span class="code">size</span> must contain the number of elements in the <span class="code">data</span> array.
		  If the HTML form contained the following elements:
		  <p><span class="code">
		      &lt;select type=checkbox name=colors value="red"&gt;<br>
		      &lt;select type=checkbox name=colors value="green"&gt;<br>
		      &lt;select type=checkbox name=colors value="blue"&gt;<br>
		  </span></p>
		  Then <span class="code">data</span> would contain "red", "green" and "blue", <span class="code">ret</span>
		  would be a 3 element integer array and <span class="code">field</span> would contain "colors".
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchMultipleString(char *field, char ***data)</span><br>
		  This function will allocate an array of strings containing the values from multiple form elements
		  of the same name.  It will also return the strings from a multiple select box. Upon success, 
		  <span class="code">GCGISUCCESS</span> is returned. If the field is not present, then 
		  <span class="code">GCGIFIELDNOTFOUND</span> is returned.  If this function is called, then the 
		  corresponding function, <span class="code">gcgiFreeMultipleString</span> must be called to free the
		  memory allocated by it.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFreeMultipleString(char **data)</span><br>
		  This function frees the memory that is allocated by the <span class="code">gcgiFetchMultipleString()</span>
		  funtion.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiFetchSelectIndex(char *field, char **data, int size, int *ret, int defaultVal)</span><br>
		  This funtion returns the index of a selected string, radio button, or set of checkboxes.  The 
		  <span class="code">data</span> parameter must contain an array of strings with the values of the radio buttons, 
		  checkboxes or multiple-select boxes.  If the field is not found, then the value in <span class="code">defaultVal</span>
		  is returned in <span class="code">ret</span>.
		</p>
		<p>
		<span class="codeHeader">gcgiResultType gcgiResetMultipleField(char *field)</span><br>
		  This function will reset GCGI's internal pointer to the first element of a field with multiple elements.  
		  After a reset, the "Next" functions will return the first element for a particular field, eventually
		  iterating through them all.
		  Upon success, <span class="code">GCGISUCCESS</span> is returned. If the field is not present, then 
		  <span class="code">GCGIFIELDNOTFOUND</span> is returned.
		</p>
	  <p><span class="subsection">Cookie-Handling Functions</span></p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiSendCookie(char *name, char *data, char *path, char *domain, char *expires, int secure, HTTPHeader header)</span><br>
	        This function will send a Cookie to the client.  It <b>must</b> be called after
	        <span class="code">gcgiSendContentType()</span> is called. Various attributes of the cookie 
	        can be set, but the only required parameters are <span class="code">name</span> and 
	        <span class="code">value</span>.  Every cookie must have a name and some data 
                that goes along with that name.  The other parameters can be <span class="code">NULL</span>. The
	        <span class="code">path</span> specifies what path on the server the cookie should be submitted
	        for and the <span class="code">domain</span> specifies to what domains the cookie should be sent.
	        The <span class="code">expires</span> parameter specifies how long the cookie should be stored, if
	        this is omitted, the cookie will be deleted when the client browser is closed.  The 
	        <span class="code">secure</span> parameter, if positive, specifies that the cookie should only be sent to secure
	        domains (HTTPS).  Finally, if this is the last HTTP header to be sent, <span class="code">header</span>
	        should be set to <span class="code">LAST</span>, otherwise set it according to the next header you are
	        going to send.  For full details of cookies, see the Netscape <a href="./cookie_spec.html">specification</a>
	        included in the <span class="code">doc/</span> directory.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiFetchCookies(char ***cookies)</span><br>
	        This function returns a NULL-terminated array of strings, each string containing a cookie that was
	        sent from the client browser to your CGI program.  If you call this function, you <b>must</b> call
	        <span class="code">gcgiFreeCookies()</span> when you are done with them to free their memory.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiParseCookie(char *cookie, char **name, char **data)</span><br>
	        This function will parse a single cookie, returning the <span class="code">name</span> of the cookie and 
	        the <span class="code">data</span> associated with it.  Generally, you will want to fetch all cookies 
	        using the <span class="code">gcgiFetchCookies() function, and then iterate through that list calling this
	        function.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiFreeCookies(char **cookies)</span><br>
	        This function frees the memory associated with an array of cookies that is created with the
	        <span class="code">gcgiFetchCookies()</span> function.
	        </p>
	        <p>
		<span class="codeHeader">gcgiReturnType  gcgiSendEncryptedCookie(char *name, char *value, char *path, char *domain, char *expires, int secure, unsigned char *key, HTTPHeader header)</span><br>
	        Identical to <span class="code">gcgiSendCookie()</span> except you must pass in a <span class="code">key</span>
	        and the cookie will be encrypted.  You must build with OpenSSL to use this function.
	        </p>
	        <p>