contrib/bsdinstaller-1.1.6/src/frontends/cgi/cgic.h

   1 /* The CGI_C library, by Thomas Boutell, version 2.01. CGI_C is intended
   2         to be a high-quality API to simplify CGI programming tasks. */
   3
   4 /* Make sure this is only included once. */
   5
   6 #ifndef CGI_C
   7 #define CGI_C 1
   8
   9 /* Bring in standard I/O since some of the functions refer to
  10         types defined by it, such as FILE *. */
  11
  12 #include <stdio.h>
  13
  14 /* The various CGI environment variables. Instead of using getenv(),
  15         the programmer should refer to these, which are always
  16         valid null-terminated strings (they may be empty, but they
  17         will never be null). If these variables are used instead
  18         of calling getenv(), then it will be possible to save
  19         and restore CGI environments, which is highly convenient
  20         for debugging. */
  21
  22 extern char *cgiServerSoftware;
  23 extern char *cgiServerName;
  24 extern char *cgiGatewayInterface;
  25 extern char *cgiServerProtocol;
  26 extern char *cgiServerPort;
  27 extern char *cgiRequestMethod;
  28 extern char *cgiPathInfo;
  29 extern char *cgiPathTranslated;
  30 extern char *cgiScriptName;
  31 extern char *cgiQueryString;
  32 extern char *cgiRemoteHost;
  33 extern char *cgiRemoteAddr;
  34 extern char *cgiAuthType;
  35 extern char *cgiRemoteUser;
  36 extern char *cgiRemoteIdent;
  37 extern char *cgiContentType;
  38 extern char *cgiAccept;
  39 extern char *cgiUserAgent;
  40 extern char *cgiReferrer;
  41
  42 /* Cookies as sent to the server. You can also get them
  43         individually, or as a string array; see the documentation. */
  44 extern char *cgiCookie;
  45
  46 /* A macro providing the same incorrect spelling that is
  47         found in the HTTP/CGI specifications */
  48 #define cgiReferer cgiReferrer
  49
  50 /* The number of bytes of data received.
  51         Note that if the submission is a form submission
  52         the library will read and parse all the information
  53         directly from cgiIn; the programmer need not do so. */
  54
  55 extern int cgiContentLength;
  56
  57 /* Pointer to CGI output. The cgiHeader functions should be used
  58         first to output the mime headers; the output HTML
  59         page, GIF image or other web document should then be written
  60         to cgiOut by the programmer. In the standard CGIC library,
  61         cgiOut is always equivalent to stdout. */
  62
  63 extern FILE *cgiOut;
  64
  65 /* Pointer to CGI input. The programmer does not read from this.
  66         We have continued to export it for backwards compatibility
  67         so that cgic 1.x applications link properly. */
  68
  69 extern FILE *cgiIn;
  70
  71 /* Possible return codes from the cgiForm family of functions (see below). */
  72
  73 typedef enum {
  74         cgiFormSuccess,
  75         cgiFormTruncated,
  76         cgiFormBadType,
  77         cgiFormEmpty,
  78         cgiFormNotFound,
  79         cgiFormConstrained,
  80         cgiFormNoSuchChoice,
  81         cgiFormMemory,
  82         cgiFormNoFileName,
  83         cgiFormNoContentType,
  84         cgiFormNotAFile,
  85         cgiFormOpenFailed,
  86         cgiFormIO,
  87         cgiFormEOF
  88 } cgiFormResultType;
  89
  90 /* These functions are used to retrieve form data. See
  91         cgic.html for documentation. */
  92
  93 extern cgiFormResultType cgiFormString(
  94         char *name, char *result, int max);
  95
  96 extern cgiFormResultType cgiFormStringNoNewlines(
  97         char *name, char *result, int max);
  98
  99
 100 extern cgiFormResultType cgiFormStringSpaceNeeded(
 101         char *name, int *length);
 102
 103
 104 extern cgiFormResultType cgiFormStringMultiple(
 105         char *name, char ***ptrToStringArray);
 106
 107 extern void cgiStringArrayFree(char **stringArray);
 108
 109 extern cgiFormResultType cgiFormInteger(
 110         char *name, int *result, int defaultV);
 111
 112 extern cgiFormResultType cgiFormIntegerBounded(
 113         char *name, int *result, int min, int max, int defaultV);
 114
 115 extern cgiFormResultType cgiFormDouble(
 116         char *name, double *result, double defaultV);
 117
 118 extern cgiFormResultType cgiFormDoubleBounded(
 119         char *name, double *result, double min, double max, double defaultV);
 120
 121 extern cgiFormResultType cgiFormSelectSingle(
 122         char *name, char **choicesText, int choicesTotal,
 123         int *result, int defaultV);
 124
 125
 126 extern cgiFormResultType cgiFormSelectMultiple(
 127         char *name, char **choicesText, int choicesTotal,
 128         int *result, int *invalid);
 129
 130 /* Just an alias; users have asked for this */
 131 #define cgiFormSubmitClicked cgiFormCheckboxSingle
 132
 133 extern cgiFormResultType cgiFormCheckboxSingle(
 134         char *name);
 135
 136 extern cgiFormResultType cgiFormCheckboxMultiple(
 137         char *name, char **valuesText, int valuesTotal,
 138         int *result, int *invalid);
 139
 140 extern cgiFormResultType cgiFormRadio(
 141         char *name, char **valuesText, int valuesTotal,
 142         int *result, int defaultV);
 143
 144 /* The paths returned by this function are the original names of files
 145         as reported by the uploading web browser and shoult NOT be
 146         blindly assumed to be "safe" names for server-side use! */
 147 extern cgiFormResultType cgiFormFileName(
 148         char *name, char *result, int max);
 149
 150 /* The content type of the uploaded file, as reported by the browser.
 151         It should NOT be assumed that browsers will never falsify
 152         such information. */
 153 extern cgiFormResultType cgiFormFileContentType(
 154         char *name, char *result, int max);
 155
 156 extern cgiFormResultType cgiFormFileSize(
 157         char *name, int *sizeP);
 158
 159 typedef struct cgiFileStruct *cgiFilePtr;
 160
 161 extern cgiFormResultType cgiFormFileOpen(
 162         char *name, cgiFilePtr *cfpp);
 163
 164 extern cgiFormResultType cgiFormFileRead(
 165         cgiFilePtr cfp, char *buffer, int bufferSize, int *gotP);
 166
 167 extern cgiFormResultType cgiFormFileClose(
 168         cgiFilePtr cfp);
 169
 170 extern cgiFormResultType cgiCookieString(
 171         char *name, char *result, int max);
 172
 173 extern cgiFormResultType cgiCookieInteger(
 174         char *name, int *result, int defaultV);
 175
 176 cgiFormResultType cgiCookies(
 177         char ***ptrToStringArray);
 178
 179 /* path can be null or empty in which case a path of / (entire site) is set.
 180         domain can be a single web site; if it is an entire domain, such as
 181         'boutell.com', it should begin with a dot: '.boutell.com' */
 182 extern void cgiHeaderCookieSetString(char *name, char *value,
 183         int secondsToLive, char *path, char *domain);
 184 extern void cgiHeaderCookieSetInteger(char *name, int value,
 185         int secondsToLive, char *path, char *domain);
 186 extern void cgiHeaderLocation(char *redirectUrl);
 187 extern void cgiHeaderStatus(int status, char *statusMessage);
 188 extern void cgiHeaderContentType(char *mimeType);
 189
 190 typedef enum {
 191         cgiEnvironmentIO,
 192         cgiEnvironmentMemory,
 193         cgiEnvironmentSuccess,
 194         cgiEnvironmentWrongVersion
 195 } cgiEnvironmentResultType;
 196
 197 extern cgiEnvironmentResultType cgiWriteEnvironment(char *filename);
 198 extern cgiEnvironmentResultType cgiReadEnvironment(char *filename);
 199
 200 extern int cgiMain(void);
 201
 202 extern cgiFormResultType cgiFormEntries(
 203         char ***ptrToStringArray);
 204
 205 /* Output string with the <, &, and > characters HTML-escaped.
 206         's' is null-terminated. Returns cgiFormIO in the event
 207         of error, cgiFormSuccess otherwise. */
 208 cgiFormResultType cgiHtmlEscape(char *s);
 209
 210 /* Output data with the <, &, and > characters HTML-escaped.
 211         'data' is not null-terminated; 'len' is the number of
 212         bytes in 'data'. Returns cgiFormIO in the event
 213         of error, cgiFormSuccess otherwise. */
 214 cgiFormResultType cgiHtmlEscapeData(char *data, int len);
 215
 216 /* Output string with the " character HTML-escaped, and no
 217         other characters escaped. This is useful when outputting
 218         the contents of a tag attribute such as 'href' or 'src'.
 219         's' is null-terminated. Returns cgiFormIO in the event
 220         of error, cgiFormSuccess otherwise. */
 221 cgiFormResultType cgiValueEscape(char *s);
 222
 223 /* Output data with the " character HTML-escaped, and no
 224         other characters escaped. This is useful when outputting
 225         the contents of a tag attribute such as 'href' or 'src'.
 226         'data' is not null-terminated; 'len' is the number of
 227         bytes in 'data'. Returns cgiFormIO in the event
 228         of error, cgiFormSuccess otherwise. */
 229 cgiFormResultType cgiValueEscapeData(char *data, int len);
 230
 231 #endif /* CGI_C */
 232