API Reference for Kerry Thomas' CGIRef

Quick Function List

Initialization Functions
cgiInit
cgiSetNullStr
cgiShutDown		 Field Access Functions 
cgiFieldPresent 
cgiGetField 
cgiGetFieldN 
cgiGetFirstField 
cgiGetNextField 		 Error Reporting Functions 
cgiErr 

Initialization Functions

Name int cgiInit(void)
Description Initializes CGIRef environment. Works for either POST or GET request. You must call this function before any API calls are made.
Returns 0 = Success 
NZ = Failure
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 printf("Content-Type: text/html%c%c",10,10); 
 if(!cgiInit())  
  { 
   ... Process ... 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Name void cgiSetNullStr(char *NullStr)
Description Sets the string to be returned when you ask for a variable that is not present. Default is NULL, until you change it. NOTE: Pass this either a NULL value or a character pointer that has global scope, i.e., not a auto variable within a function, as illustrated below
Returns Nothing
Example
Correct #include <stdio.h> 
#include <cgi/cgi.h> 

char *BadField="Field Not Found"; 

void SomeFunc(void) 
{ 
 cgiSetNullStr(BadField); 
}
Incorrect #include <stdio.h> 
#include <cgi/cgi.h> 

void SomeFunc(void) 
{ 
 char *BadField="Field Not Found"; 
 cgiSetNullStr(BadField);    /* Bad idea -- "BadField" passes      */ 
                             /* out of scope and becomes undefined */ 
}

Name int cgiShutDown(void)
Description Shuts down the library, frees all allocated memory, and marks library as unusable
Returns Nothing
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 printf("Content-Type: text/html%c%c",10,10); 
 if(!cgiInit())  
  { 
   ... Process ... 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Field Access Functions

Name int cgiFieldPresent(char *FieldName)
Description Determines if the named field is present
Returns 1 = Field is present 
0 = Field is not present
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 printf("Content-Type: text/html%c%c",10,10); 

 if(!cgiInit()) 
  { 
   if(cgiFieldPresent("Name")) 
    ... Process ... 
   else 
    printf("<H1>Cannot find required field</H1>%c",10); 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Name char *cgiGetField(char *FieldName)
Description Get the value of the named field, if any.
Returns String containing value of field. If field requested is not found, NULL is returned, unless cgiSetNullStr( ) was called.
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
  char *NameValue=0; 

 printf("Content-Type: text/html%c%c",10,10); 

 if(!cgiInit())  
  { 
   if((NameValue=cgiGetField("Name"))) 
    printf("You entered: %s%c",NameValue,10) 
   else 
    printf("<H1>Cannot find required field</H1>%c",10) 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Name char *cgiGetFieldN(char *FieldName,int n)
Description Get the Nth Occurence of the named field.
Returns String containing value of nth occurence of the named field. If field requested is not found, or if n is greater than the number of occurences of that field less 1, NULL is returned, unless cgiSetNullStr( ) was called. For example, if the field "PartNum" is in a submitted form six times, cgiGetField("PartNum",5) will return the last occurence. cgiGetField("PartNum",6) will return a NULL. Actually, cgiGetField( ) calls this function with a 0 parameter.
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 printf("Content-Type: text/html%c%c",10,10); 
  
 if(!cgiInit()) 
  { 
   ... Process ... 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Name int cgiGetFirstField(char **Name, char **Value)
Description Gets the Name and Value of the first of all fields submitted.
Returns 0 = Success, *Name and *Value now point to name & value of field 
NZ = Failure, *Name and *Value unmodified.
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 char *NamePtr; 
 char *ValPtr; 

 printf("Content-Type: text/html%c%c",10,10); 

 if(!cgiInit()) 
  { 
   if(cgiGetFirstField(&NamePtr,&ValPtr)) 
   do 
    printf("%s=%s<BR>%c",NamePtr,ValPtr,10) 
   while(cgiGetNextField(&NamePtr,&ValPtr)); 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
} 

Name int cgiGetNextField(char **Name, char **Value)
Description Gets the Name and Value of the next field. Intended to be called after cgiGetFirstField( ).
Returns 0 = Success, *Name and *Value now point to name & value of next field 
NZ = Failure, *Name and *Value unmodified.
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 char *NamePtr; 
 char *ValPtr; 

 printf("Content-Type: text/html%c%c",10,10); 

 if(!cgiInit()) 
  { 
   if(cgiGetFirstField(&NamePtr,&ValPtr)) 
   do 
    printf("%s=%s<BR>%c",NamePtr,ValPtr,10) 
   while(cgiGetNextField(&NamePtr,&ValPtr)); 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
}

Error Reporting Functions

Name int cgiErr(void)
Description Returns last error generated by cgiRef.
Returns Last error encountered by CGIRef
Example #include <stdio.h> 
#include <cgi/cgi.h> 

int main(int argc, char *argv[]) 
{ 
 printf("Content-Type: text/html%c%c",10,10); 
 if(!cgiInit())  
  { 
   ... Process ... 
  } 
 else 
  printf("<H1>Cannot initalize CGI Environment:%d</H1>%c",cgiErr(),10); 

 cgiShutDown(); 
}