# CGI API

Header | cups/cgi.h
--- | ---
Library | -lcupscgi
See Also | Programming: Introduction to CUPS Programming

## Contents

- Overview
- Functions
  - cgiCheckVariables
  - cgiClearVariables
  - cgiCompileSearch
  - cgiCopyTemplateFile
  - cgiCopyTemplateLang
  - cgiDoSearch
  - cgiEndHTML
  - cgiEndMultipart
  - cgiFormEncode
  - cgiFreeSearch
  - cgiGetArray
  - cgiGetAttributes
  - cgiGetCookie
  - cgiGetFile
  - cgiGetIPPObjects
  - cgiGetSize
  - cgiGetTemplateDir
  - cgiGetVariable
  - cgiInitialize
  - cgiIsPOST
  - cgiMoveJobs
  - cgiPrintCommand
  - cgiPrintTestPage
  - cgiRewriteURL
  - cgiSetArray
  - cgiSetCookie
  - cgiSetIPPObjectVars
  - cgiSetIPPVars
  - cgiSetServerVersion
  - cgiSetSize
  - cgiSetVariable
  - cgiShowIPPError
  - cgiShowJobs
  - cgiStartHTML
  - cgiStartMultipart
  - cgiSupportsMultipart
  - cgiText
  - helpDeleteIndex
  - helpFindNode
  - helpLoadIndex
  - helpSaveIndex
  - helpSearchIndex
- Data Types
  - cgi_file_t
  - help_index_t
  - help_node_t
  - help_word_t
- Structures
  - cgi_file_s
  - help_index_s
  - help_node_s
  - help_word_s

## Overview

The CGI API provides Common Gateway Interface functions for CUPS.

## Functions

### cgiCheckVariables

Check for the presence of "required" variables.

int cgiCheckVariables (
const char *names
);

#### Parameters

names
  Variables to look for

#### Return Value

1 if all variables present, 0 otherwise

#### Discussion

Names may be separated by spaces and/or commas.

### cgiClearVariables

Clear all form variables.

void cgiClearVariables (void);

### cgiCompileSearch

Compile a search string.

void *cgiCompileSearch (
const char *query
);

#### Parameters

query
  Query string

#### Return Value

Search context

### cgiCopyTemplateFile

Copy a template file and replace all the '{variable}' strings with the variable value.

void cgiCopyTemplateFile (
FILE *out,
const char *tmpl
);

#### Parameters

out
  Output file
tmpl
  Template file to read

### cgiCopyTemplateLang

Copy a template file using a language...

void cgiCopyTemplateLang (
const char *tmpl
);

#### Parameters

tmpl
  Base filename

### cgiDoSearch

Do a search of some text.

int cgiDoSearch (
void *search,
const char *text
);

#### Parameters

search
  Search context
text
  Text to search

#### Return Value

Number of matches

### cgiEndHTML

End a HTML page.

void cgiEndHTML (void);

### cgiEndMultipart

End the delivery of a multipart web page.

void cgiEndMultipart (void);

### cgiFormEncode

Encode a string as a form variable.

char *cgiFormEncode (
char *dst,
const char *src,
size_t dstsize
);

#### Parameters

dst
  Destination string
src
  Source string
dstsize
  Size of destination string

#### Return Value

Destination string

### cgiFreeSearch

Free a compiled search context.

void cgiFreeSearch (
void *search
);

#### Parameters

search
  Search context

### cgiGetArray

Get an element from a form array.

const char *cgiGetArray (
const char *name,
int element
);

#### Parameters

name
  Name of array variable
element
  Element number (0 to N)

#### Return Value

Element value or NULL

### cgiGetAttributes

Get the list of attributes that are needed by the template file.

void cgiGetAttributes (
ipp_t *request,
const char *tmpl
);

#### Parameters

request
  IPP request
tmpl
  Base filename

### cgiGetCookie

Get a cookie value.

const char *cgiGetCookie (
const char *name
);

#### Parameters

name
  Name of cookie

#### Return Value

Value or NULL

### cgiGetFile

Get the file (if any) that was submitted in the form.

const cgi_file_t *cgiGetFile (void);

#### Return Value

Attached file or NULL

### cgiGetIPPObjects

Get the objects in an IPP response.

cups_array_t *cgiGetIPPObjects (
ipp_t *response,
void *search
);

#### Parameters

response
  IPP response
search
  Search filter

#### Return Value

Array of objects

### cgiGetSize

Get the size of a form array value.

int cgiGetSize (
const char *name
);

#### Parameters

name
  Name of variable

#### Return Value

Number of elements

### cgiGetTemplateDir

Get the templates directory...

char *cgiGetTemplateDir (void);

#### Return Value

Template directory

### cgiGetVariable

Get a CGI variable from the database.

const char *cgiGetVariable (
const char *name
);

#### Parameters

name
  Name of variable

#### Return Value

Value of variable

#### Discussion

Returns NULL if the variable doesn't exist. If the variable is an array of values, returns the last element.

### cgiInitialize

Initialize the CGI variable "database".

int cgiInitialize (void);

#### Return Value

Non-zero if there was form data

### cgiIsPOST

Determine whether this page was POSTed.

int cgiIsPOST (void);

#### Return Value

1 if POST, 0 if GET

### cgiMoveJobs

Move one or more jobs.

void cgiMoveJobs (
http_t *http,
const char *dest,
int job_id
);

#### Parameters

http
  Connection to server
dest
  Destination or NULL
job_id
  Job ID or 0 for all

#### Discussion

At least one of dest or job_id must be non-zero/NULL.

### cgiPrintCommand

Print a CUPS command job.

void cgiPrintCommand (
http_t *http,
const char *dest,
const char *command,
const char *title
);

#### Parameters

http
  Connection to server
dest
  Destination printer
command
  Command to send
title
  Page/job title

### cgiPrintTestPage

Print a test page.

void cgiPrintTestPage (
http_t *http,
const char *dest
);

#### Parameters

http
  Connection to server
dest
  Destination printer/class

### cgiRewriteURL

Rewrite a printer URI into a web browser URL...

char *cgiRewriteURL (
const char *uri,
char *url,
int urlsize,
const char *newresource
);

#### Parameters

uri
  Current URI
url
  New URL
urlsize
  Size of URL buffer
newresource
  Replacement resource

#### Return Value

New URL

### cgiSetArray

Set array element N to the specified string.

void cgiSetArray (
const char *name,
int element,
const char *value
);

#### Parameters

name
  Name of variable
element
  Element number (0 to N)
value
  Value of variable

#### Discussion

If the variable array is smaller than (element + 1), the intervening elements are set to NULL.

### cgiSetCookie

Set a cookie value.

void cgiSetCookie (
const char *name,
const char *value,
const char *path,
const char *domain,
time_t expires,
int secure
);

#### Parameters

name
  Name
value
  Value
path
  Path (typically "/")
domain
  Domain name
expires
  Expiration date (0 for session)
secure
  Require SSL

### cgiSetIPPObjectVars

Set CGI variables from an IPP object.

ipp_attribute_t *cgiSetIPPObjectVars (
ipp_attribute_t *obj,
const char *prefix,
int element
);

#### Parameters

obj
  Response data to be copied...
prefix
  Prefix for name or NULL
element
  Parent element number

#### Return Value

Next object

### cgiSetIPPVars

Set CGI variables from an IPP response.

int cgiSetIPPVars (
ipp_t *response,
const char *filter_name,
const char *filter_value,
const char *prefix,
int parent_el
);

#### Parameters

response
  Response data to be copied...
filter_name
  Filter name
filter_value
  Filter value
prefix
  Prefix for name or NULL
parent_el
  Parent element number

#### Return Value

Maximum number of elements

### cgiSetServerVersion

Set the server name and CUPS version...

void cgiSetServerVersion (void);

### cgiSetSize

Set the array size.

void cgiSetSize (
const char *name,
int size
);

#### Parameters

name
  Name of variable
size
  Number of elements (0 to N)

### cgiSetVariable

Set a CGI variable in the database.

void cgiSetVariable (
const char *name,
const char *value
);

#### Parameters

name
  Name of variable
value
  Value of variable

#### Discussion

If the variable is an array, this truncates the array to a single element.

### cgiShowIPPError

Show the last IPP error message.

void cgiShowIPPError (
const char *message
);

#### Parameters

message
  Contextual message

#### Discussion

The caller must still call cgiStartHTML() and cgiEndHTML().

### cgiShowJobs

Show print jobs.

void cgiShowJobs (
http_t *http,
const char *dest
);

#### Parameters

http
  Connection to server
dest
  Destination name or NULL

### cgiStartHTML

Start a HTML page.

void cgiStartHTML (
const char *title
);

#### Parameters

title
  Title of page

### cgiStartMultipart

Start a multipart delivery of a web page.

void cgiStartMultipart (void);

### cgiSupportsMultipart

Does the browser support multi-part documents?

int cgiSupportsMultipart (void);

#### Return Value

1 if multi-part supported, 0 otherwise

### cgiText

Return localized text.

const char *cgiText (
const char *message
);

#### Parameters

message
  Message

#### Return Value

Localized message

### helpDeleteIndex

Delete an index, freeing all memory used.

void helpDeleteIndex (
help_index_t *hi
);

#### Parameters

hi
  Help index

### helpFindNode

Find a node in an index.

help_node_t *helpFindNode (
help_index_t *hi,
const char *filename,
const char *anchor
);

#### Parameters

hi
  Index
filename
  Filename
anchor
  Anchor

#### Return Value

Node pointer or NULL

### helpLoadIndex

Load a help index from disk.

help_index_t *helpLoadIndex (
const char *hifile,
const char *directory
);

#### Parameters

hifile
  Index filename
directory
  Directory that is indexed

#### Return Value

Index pointer or NULL

### helpSaveIndex

Save a help index to disk.

int helpSaveIndex (
help_index_t *hi,
const char *hifile
);

#### Parameters

hi
  Index
hifile
  Index filename

#### Return Value

0 on success, -1 on error

### helpSearchIndex

Search an index.

help_index_t *helpSearchIndex (
help_index_t *hi,
const char *query,
const char *section,
const char *filename
);

#### Parameters

hi
  Index
query
  Query string
section
  Limit search to this section
filename
  Limit search to this file

#### Return Value

Search index

## Data Types

### cgi_file_t

Uploaded file data

typedef struct cgi_file_s cgi_file_t;

### help_index_t

Help index structure

typedef struct help_index_s help_index_t;

### help_node_t

Help node structure...

typedef struct help_node_s help_node_t;

### help_word_t

Help word structure...

typedef struct help_word_s help_word_t;

## Structures

### cgi_file_s

Uploaded file data

struct cgi_file_s {
size_t filesize;
char tempfile[1024], *name, *filename, *mimetype;
};

#### Members

filesize
  Size of uploaded file
mimetype
  MIME media type

### help_index_s

Help index structure

struct help_index_s {
cups_array_t *nodes;
int search;
cups_array_t *sorted;
};

#### Members

nodes
  Nodes sorted by filename
search
  1 = search index, 0 = normal
sorted
  Nodes sorted by score + text

### help_node_s

Help node structure...

struct help_node_s {
char *anchor;
char *filename;
size_t length;
time_t mtime;
off_t offset;
int score;
char *section;
char *text;
cups_array_t *words;
};

#### Members

anchor
  Anchor name (NULL if none)
filename
  Filename, relative to help dir
length
  Length in bytes
mtime
  Last modification time
offset
  Offset in file
score
  Search score
section
  Section name (NULL if none)
text
  Text in anchor
words
  Words after this node

### help_word_s

Help word structure...

struct help_word_s {
int count;
char *text;
};

#### Members

count
  Number of occurrences
text
  Word text