CGI API

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