CGI API

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

Contents

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