Introduction

The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP protocols and CUPS scheduler. They are typically used by monitoring and administration programs to perform specific functions not supported by the high-level CUPS API functions.

General Usage

The <cups/cups.h> header file must be included to use the HTTP and IPP functions.

Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library:

gcc -o myprogram myprogram.c -lcups

Compatibility

Unless otherwise specified, the HTTP and IPP API functions require CUPS 1.1 or higher.

Contents

• Enumerations
• Functions
• Structures
• Types
• Unions

Enumerations

• http_auth_e
• http_encoding_e
• http_encryption_e
• http_field_e
• http_keepalive_e
• http_state_e
• http_status_e
• http_uri_coding_e
• http_uri_status_e
• http_version_e
• ipp_finish_e
• ipp_jstate_e
• ipp_op_e
• ipp_orient_e
• ipp_pstate_e
• ipp_quality_e
• ipp_res_e
• ipp_state_e
• ipp_status_e
• ipp_tag_e

http_auth_e

Description

HTTP authentication types

Values

http_encoding_e

Description

HTTP transfer encoding values

Values

http_encryption_e

Description

HTTP encryption values

Values

http_field_e

Description

HTTP field names

Values

http_keepalive_e

Description

Types and structures...

Values

http_state_e

Description

Values

http_status_e

Description

HTTP status codes

Values

http_uri_coding_e

Description

Values

http_uri_status_e

Description

Values

http_version_e

Description

Values

ipp_finish_e

Description

Values

ipp_jstate_e

Description

Values

ipp_op_e

Description

Values

ipp_orient_e

Description

Values

ipp_pstate_e

Description

Values

ipp_quality_e

Description

Values

ipp_res_e

Description

Types and structures...

Values

ipp_state_e

Description

Values

ipp_status_e

Description

IPP status codes...

Values

ipp_tag_e

Description

Format tags for attributes...

Values

Functions

• cupsDoAuthentication()  CUPS 1.1.20 
• cupsDoFileRequest()
• cupsDoIORequest()  CUPS 1.3 
• cupsDoRequest()
• cupsEncodeOptions()
• cupsEncodeOptions2()  CUPS 1.2 
• httpAddrAny()  CUPS 1.2 
• httpAddrEqual()  CUPS 1.2 
• httpAddrLength()  CUPS 1.2 
• httpAddrLocalhost()  CUPS 1.2 
• httpAddrLookup()  CUPS 1.2 
• httpAddrString()  CUPS 1.2 
• httpAssembleURI()  CUPS 1.2 
• httpAssembleURIf()  CUPS 1.2 
• httpBlocking()
• httpCheck()
• httpClearCookie()  CUPS 1.1.19 
• httpClearFields()
• httpClose()
• httpConnect()
• httpConnectEncrypt()
• httpDecode64()  DEPRECATED 
• httpDecode64_2()  CUPS 1.1.21 
• httpDelete()
• httpEncode64()  DEPRECATED 
• httpEncode64_2()  CUPS 1.1.21 
• httpEncryption()
• httpError()
• httpFlush()
• httpFlushWrite()  CUPS 1.2 
• httpGet()
• httpGetAuthString()  CUPS 1.3 
• httpGetBlocking()  CUPS 1.2 
• httpGetCookie()  CUPS 1.1.19 
• httpGetDateString()  DEPRECATED 
• httpGetDateString2()  CUPS 1.2 
• httpGetDateTime()
• httpGetFd()  CUPS 1.2 
• httpGetField()
• httpGetHostByName()  DEPRECATED 
• httpGetHostname()  CUPS 1.2 
• httpGetLength()  DEPRECATED 
• httpGetLength2()  CUPS 1.2 
• httpGetStatus()  CUPS 1.2 
• httpGetSubField()  DEPRECATED 
• httpGetSubField2()  CUPS 1.2 
• httpGets()
• httpHead()
• httpInitialize()
• httpMD5()
• httpMD5Final()
• httpMD5String()
• httpOptions()
• httpPost()
• httpPut()
• httpRead()  DEPRECATED 
• httpRead2()  CUPS 1.2 
• httpReconnect()
• httpSeparate()  DEPRECATED 
• httpSeparate2()  CUPS 1.1.21 
• httpSeparateURI()  CUPS 1.2 
• httpSetAuthString()  CUPS 1.3 
• httpSetCookie()  CUPS 1.1.19 
• httpSetExpect()  CUPS 1.2 
• httpSetField()
• httpSetLength()  CUPS 1.2 
• httpStatus()
• httpTrace()
• httpUpdate()
• httpWait()  CUPS 1.1.19 
• httpWrite()  DEPRECATED 
• httpWrite2()  CUPS 1.2 
• ippAddBoolean()
• ippAddBooleans()
• ippAddCollection()  CUPS 1.1.19 
• ippAddCollections()  CUPS 1.1.19 
• ippAddDate()
• ippAddInteger()
• ippAddIntegers()
• ippAddOctetString()  CUPS 1.2 
• ippAddRange()
• ippAddRanges()
• ippAddResolution()
• ippAddResolutions()
• ippAddSeparator()
• ippAddString()
• ippAddStrings()
• ippDateToTime()
• ippDelete()
• ippDeleteAttribute()  CUPS 1.1.19 
• ippErrorString()
• ippErrorValue()  CUPS 1.2 
• ippFindAttribute()
• ippFindNextAttribute()
• ippLength()
• ippNew()
• ippNewRequest()  CUPS 1.2 
• ippOpString()  CUPS 1.2 
• ippOpValue()  CUPS 1.2 
• ippPort()
• ippRead()
• ippReadFile()  CUPS 1.1.19 
• ippReadIO()  CUPS 1.2 
• ippSetPort()
• ippTimeToDate()
• ippWrite()
• ippWriteFile()  CUPS 1.1.19 
• ippWriteIO()  CUPS 1.2 

 CUPS 1.1.20 cupsDoAuthentication()

Description

Authenticate a request.

This function should be called in response to a HTTP_UNAUTHORIZED status, prior to resubmitting your request.

Syntax

int
cupsDoAuthentication( http_t * http, const char * method, const char * resource);

Arguments

Returns

0 on success, -1 on error

cupsDoFileRequest()

Description

Do an IPP request with a file.

This function sends the IPP request to the specified server, retrying and authenticating as necessary. The request is freed with ippDelete() after receiving a valid IPP response.

Syntax

ipp_t *
cupsDoFileRequest( http_t * http, ipp_t * request, const char * resource, const char * filename);

Arguments

Returns

Response data

 CUPS 1.3 cupsDoIORequest()

Description

Do an IPP request with file descriptors.

This function sends the IPP request to the specified server, retrying and authenticating as necessary. The request is freed with ippDelete() after receiving a valid IPP response.

If "infile" is a valid file descriptor, cupsDoIORequest() copies all of the data from the file after the IPP request message.

If "outfile" is a valid file descriptor, cupsDoIORequest() copies all of the data after the IPP response message to the file.

Syntax

ipp_t *
cupsDoIORequest( http_t * http, ipp_t * request, const char * resource, int infile, int outfile);

Arguments

Returns

Response data

cupsDoRequest()

Description

Do an IPP request.

This function sends the IPP request to the specified server, retrying and authenticating as necessary. The request is freed with ippDelete() after receiving a valid IPP response.

Syntax

ipp_t *
cupsDoRequest( http_t * http, ipp_t * request, const char * resource);

Arguments

Returns

Response data

cupsEncodeOptions()

Description

Encode printer options into IPP attributes.

This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.

Syntax

void
cupsEncodeOptions( ipp_t * ipp, int num_options, cups_option_t * options);

Arguments

Returns

Nothing.

 CUPS 1.2 cupsEncodeOptions2()

Description

Encode printer options into IPP attributes for a group.

This function only adds attributes for a single group. Call this function multiple times for each group, or use cupsEncodeOptions() to add the standard groups.

Syntax

void
cupsEncodeOptions2( ipp_t * ipp, int num_options, cups_option_t * options, ipp_tag_t group_tag);

Arguments

Returns

Nothing.

 CUPS 1.2 httpAddrAny()

Description

Check for the "any" address.

Syntax

int
httpAddrAny( const http_addr_t * addr);

Arguments

Returns

1 if "any", 0 otherwise

 CUPS 1.2 httpAddrEqual()

Description

Compare two addresses.

Syntax

int
httpAddrEqual( const http_addr_t * addr1, const http_addr_t * addr2);

Arguments

Returns

1 if equal, 0 if not

 CUPS 1.2 httpAddrLength()

Description

Return the length of the address in bytes.

Syntax

int
httpAddrLength( const http_addr_t * addr);

Arguments

Returns

Length in bytes

 CUPS 1.2 httpAddrLocalhost()

Description

Check for the local loopback address.

Syntax

int
httpAddrLocalhost( const http_addr_t * addr);

Arguments

Returns

1 if local host, 0 otherwise

 CUPS 1.2 httpAddrLookup()

Description

Lookup the hostname associated with the address.

Syntax

char *
httpAddrLookup( const http_addr_t * addr, char * name, int namelen);

Arguments

Returns

Host name

 CUPS 1.2 httpAddrString()

Description

Convert an address to a numeric string.

Syntax

char *
httpAddrString( const http_addr_t * addr, char * s, int slen);

Arguments

Returns

Numeric address string

 CUPS 1.2 httpAssembleURI()

Description

Assemble a uniform resource identifier from its components.

This function escapes reserved characters in the URI depending on the value of the "encoding" argument. You should use this function in place of traditional string functions whenever you need to create a URI string.

Syntax

http_uri_status_t
httpAssembleURI( http_uri_coding_t encoding, char * uri, int urilen, const char * scheme, const char * username, const char * host, int port, const char * resource);

Arguments

Returns

URI status

 CUPS 1.2 httpAssembleURIf()

Description

Assemble a uniform resource identifier from its components with a formatted resource.

This function creates a formatted version of the resource string argument "resourcef" and escapes reserved characters in the URI depending on the value of the "encoding" argument. You should use this function in place of traditional string functions whenever you need to create a URI string.

Syntax

http_uri_status_t
httpAssembleURIf( http_uri_coding_t encoding, char * uri, int urilen, const char * scheme, const char * username, const char * host, int port, const char * resourcef, ...);

Arguments

Returns

URI status

httpBlocking()

Description

Set blocking/non-blocking behavior on a connection.

Syntax

void
httpBlocking( http_t * http, int b);

Arguments

Returns

Nothing.

httpCheck()

Description

Check to see if there is a pending response from the server.

Syntax

int
httpCheck( http_t * http);

Arguments

Returns

0 = no data, 1 = data available

 CUPS 1.1.19 httpClearCookie()

Description

Clear the cookie value(s).

Syntax

void
httpClearCookie( http_t * http);

Arguments

Returns

Nothing.

httpClearFields()

Description

Clear HTTP request fields.

Syntax

void
httpClearFields( http_t * http);

Arguments

Returns

Nothing.

httpClose()

Description

Close an HTTP connection...

Syntax

void
httpClose( http_t * http);

Arguments

Returns

Nothing.

httpConnect()

Description

Connect to a HTTP server.

Syntax

http_t *
httpConnect( const char * host, int port);

Arguments

Returns

New HTTP connection

httpConnectEncrypt()

Description

Connect to a HTTP server using encryption.

Syntax

http_t *
httpConnectEncrypt( const char * host, int port, http_encryption_t encryption);

Arguments

Returns

New HTTP connection

 DEPRECATED httpDecode64()

Description

Base64-decode a string.

This function is deprecated. Use the httpDecode64_2() function instead which provides buffer length arguments.

Syntax

char *
httpDecode64( char * out, const char * in);

Arguments

Returns

Decoded string

 CUPS 1.1.21 httpDecode64_2()

Description

Base64-decode a string.

Syntax

char *
httpDecode64_2( char * out, int * outlen, const char * in);

Arguments

Returns

Decoded string

httpDelete()

Description

Send a DELETE request to the server.

Syntax

int
httpDelete( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

 DEPRECATED httpEncode64()

Description

Base64-encode a string.

This function is deprecated. Use the httpEncode64_2() function instead which provides buffer length arguments.

Syntax

char *
httpEncode64( char * out, const char * in);

Arguments

Returns

Encoded string

 CUPS 1.1.21 httpEncode64_2()

Description

Base64-encode a string.

Syntax

char *
httpEncode64_2( char * out, int outlen, const char * in, int inlen);

Arguments

Returns

Encoded string

httpEncryption()

Description

Set the required encryption on the link.

Syntax

int
httpEncryption( http_t * http, http_encryption_t e);

Arguments

Returns

-1 on error, 0 on success

httpError()

Description

Get the last error on a connection.

Syntax

int
httpError( http_t * http);

Arguments

Returns

Error code (errno) value

httpFlush()

Description

Flush data from a HTTP connection.

Syntax

void
httpFlush( http_t * http);

Arguments

Returns

Nothing.

 CUPS 1.2 httpFlushWrite()

Description

Flush data in write buffer.

Syntax

int
httpFlushWrite( http_t * http);

Arguments

Returns

Bytes written or -1 on error

httpGet()

Description

Send a GET request to the server.

Syntax

int
httpGet( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

 CUPS 1.3 httpGetAuthString()

Description

Get the current authorization string.

The authorization string is set by cupsDoAuthentication() and httpSetAuthString(). Use httpGetAuthString() to retrieve the string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION value.

Syntax

char *
httpGetAuthString( http_t * http);

Arguments

Returns

Authorization string

 CUPS 1.2 httpGetBlocking()

Description

Get the blocking/non-block state of a connection.

Syntax

int
httpGetBlocking( http_t * http);

Arguments

Returns

1 if blocking, 0 if non-blocking

 CUPS 1.1.19 httpGetCookie()

Description

Get any cookie data from the response.

Syntax

const char *
httpGetCookie( http_t * http);

Arguments

Returns

Cookie data or NULL

 DEPRECATED httpGetDateString()

Description

Get a formatted date/time string from a time value.

Syntax

const char *
httpGetDateString( time_t t);

Arguments

Returns

Date/time string

 CUPS 1.2 httpGetDateString2()

Description

Get a formatted date/time string from a time value.

Syntax

const char *
httpGetDateString2( time_t t, char * s, int slen);

Arguments

Returns

Date/time string

httpGetDateTime()

Description

Get a time value from a formatted date/time string.

Syntax

time_t
httpGetDateTime( const char * s);

Arguments

Returns

UNIX time

 CUPS 1.2 httpGetFd()

Description

Get the file descriptor associated with a connection.

Syntax

int
httpGetFd( http_t * http);

Arguments

Returns

File descriptor or -1 if none

httpGetField()

Description

Get a field value from a request/response.

Syntax

const char *
httpGetField( http_t * http, http_field_t field);

Arguments

Returns

Field value

 DEPRECATED httpGetHostByName()

Description

Lookup a hostname or IPv4 address, and return address records for the specified name.

Syntax

struct hostent *
httpGetHostByName( const char * name);

Arguments

Returns

Host entry

 CUPS 1.2 httpGetHostname()

Description

Get the FQDN for the connection or local system.

When "http" points to a connected socket, return the hostname or address that was used in the call to httpConnect() or httpConnectEncrypt(). Otherwise, return the FQDN for the local system using both gethostname() and gethostbyname() to get the local hostname with domain.

Syntax

const char *
httpGetHostname( http_t * http, char * s, int slen);

Arguments

Returns

FQDN for connection or system

 DEPRECATED httpGetLength()

Description

Get the amount of data remaining from the content-length or transfer-encoding fields.

This function is deprecated and will not return lengths larger than 2^31 - 1; use httpGetLength2() instead.

Syntax

int
httpGetLength( http_t * http);

Arguments

Returns

Content length

 CUPS 1.2 httpGetLength2()

Description

Get the amount of data remaining from the content-length or transfer-encoding fields.

This function returns the complete content length, even for content larger than 2^31 - 1.

Syntax

off_t
httpGetLength2( http_t * http);

Arguments

Returns

Content length

 CUPS 1.2 httpGetStatus()

Description

Get the status of the last HTTP request.

Syntax

http_status_t
httpGetStatus( http_t * http);

Arguments

Returns

HTTP status

 DEPRECATED httpGetSubField()

Description

Get a sub-field value.

Syntax

char *
httpGetSubField( http_t * http, http_field_t field, const char * name, char * value);

Arguments

Returns

Value or NULL

 CUPS 1.2 httpGetSubField2()

Description

Get a sub-field value.

Syntax

char *
httpGetSubField2( http_t * http, http_field_t field, const char * name, char * value, int valuelen);

Arguments

Returns

Value or NULL

httpGets()

Description

Get a line of text from a HTTP connection.

Syntax

char *
httpGets( char * line, int length, http_t * http);

Arguments

Returns

Line or NULL

httpHead()

Description

Send a HEAD request to the server.

Syntax

int
httpHead( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

httpInitialize()

Description

Initialize the HTTP interface library and set the default HTTP proxy (if any).

Syntax

void
httpInitialize(void);

Arguments

None.

Returns

Nothing.

httpMD5()

Description

Compute the MD5 sum of the username:group:password.

Syntax

char *
httpMD5( const char * username, const char * realm, const char * passwd, char md5[33]);

Arguments

Returns

MD5 sum

httpMD5Final()

Description

Combine the MD5 sum of the username, group, and password with the server-supplied nonce value, method, and request-uri.

Syntax

char *
httpMD5Final( const char * nonce, const char * method, const char * resource, char md5[33]);

Arguments

Returns

New sum

httpMD5String()

Description

Convert an MD5 sum to a character string.

Syntax

char *
httpMD5String( const unsigned char * sum, char md5[33]);

Arguments

Returns

MD5 sum in hex

httpOptions()

Description

Send an OPTIONS request to the server.

Syntax

int
httpOptions( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

httpPost()

Description

Send a POST request to the server.

Syntax

int
httpPost( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

httpPut()

Description

Send a PUT request to the server.

Syntax

int
httpPut( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

 DEPRECATED httpRead()

Description

Read data from a HTTP connection.

This function is deprecated. Use the httpRead2() function which can read more than 2GB of data.

Syntax

int
httpRead( http_t * http, char * buffer, int length);

Arguments

Returns

Number of bytes read

 CUPS 1.2 httpRead2()

Description

Read data from a HTTP connection.

Syntax

ssize_t
httpRead2( http_t * http, char * buffer, size_t length);

Arguments

Returns

Number of bytes read

httpReconnect()

Description

Reconnect to a HTTP server.

Syntax

int
httpReconnect( http_t * http);

Arguments

Returns

0 on success, non-zero on failure

 DEPRECATED httpSeparate()

Description

Separate a Universal Resource Identifier into its components.

This function is deprecated; use the httpSeparateURI() function instead.

Syntax

void
httpSeparate( const char * uri, char * scheme, char * username, char * host, int * port, char * resource);

Arguments

Returns

Nothing.

 CUPS 1.1.21 httpSeparate2()

Description

Separate a Universal Resource Identifier into its components.

This function is deprecated; use the httpSeparateURI() function instead.

Syntax

void
httpSeparate2( const char * uri, char * scheme, int schemelen, char * username, int usernamelen, char * host, int hostlen, int * port, char * resource, int resourcelen);

Arguments

Returns

Nothing.

 CUPS 1.2 httpSeparateURI()

Description

Separate a Universal Resource Identifier into its components.

Syntax

http_uri_status_t
httpSeparateURI( http_uri_coding_t decoding, const char * uri, char * scheme, int schemelen, char * username, int usernamelen, char * host, int hostlen, int * port, char * resource, int resourcelen);

Arguments

Returns

Result of separation

 CUPS 1.3 httpSetAuthString()

Description

Set the current authorization string.

This function just stores a copy of the current authorization string in the HTTP connection object. You must still call httpSetField() to set HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(), httpHead(), httpOptions(), httpPost, or httpPut().

Syntax

void
httpSetAuthString( http_t * http, const char * scheme, const char * data);

Arguments

Returns

Nothing.

 CUPS 1.1.19 httpSetCookie()

Description

Set the cookie value(s)...

Syntax

void
httpSetCookie( http_t * http, const char * cookie);

Arguments

Returns

Nothing.

 CUPS 1.2 httpSetExpect()

Description

Set the Expect: header in a request.

Currently only HTTP_CONTINUE is supported for the "expect" argument.

Syntax

void
httpSetExpect( http_t * http, http_status_t expect);

Arguments

Returns

Nothing.

httpSetField()

Description

Set the value of an HTTP header.

Syntax

void
httpSetField( http_t * http, http_field_t field, const char * value);

Arguments

Returns

Nothing.

 CUPS 1.2 httpSetLength()

Description

Set the content-length and content-encoding.

Syntax

void
httpSetLength( http_t * http, size_t length);

Arguments

Returns

Nothing.

httpStatus()

Description

Return a short string describing a HTTP status code.

Syntax

const char *
httpStatus( http_status_t status);

Arguments

Returns

String or NULL

httpTrace()

Description

Send an TRACE request to the server.

Syntax

int
httpTrace( http_t * http, const char * uri);

Arguments

Returns

Status of call (0 = success)

httpUpdate()

Description

Update the current HTTP state for incoming data.

Syntax

http_status_t
httpUpdate( http_t * http);

Arguments

Returns

HTTP status

 CUPS 1.1.19 httpWait()

Description

Wait for data available on a connection.

Syntax

int
httpWait( http_t * http, int msec);

Arguments

Returns

1 if data is available, 0 otherwise

 DEPRECATED httpWrite()

Description

Write data to a HTTP connection.

This function is deprecated. Use the httpWrite2() function which can write more than 2GB of data.

Syntax

int
httpWrite( http_t * http, const char * buffer, int length);

Arguments

Returns

Number of bytes written

 CUPS 1.2 httpWrite2()

Description

Write data to a HTTP connection.

Syntax

ssize_t
httpWrite2( http_t * http, const char * buffer, size_t length);

Arguments

Returns

Number of bytes written

ippAddBoolean()

Description

Add a boolean attribute to an IPP message.

Syntax

ipp_attribute_t *
ippAddBoolean( ipp_t * ipp, ipp_tag_t group, const char * name, char value);

Arguments

Returns

New attribute

ippAddBooleans()

Description

Add an array of boolean values.

Syntax

ipp_attribute_t *
ippAddBooleans( ipp_t * ipp, ipp_tag_t group, const char * name, int num_values, const char * values);

Arguments

Returns

New attribute

 CUPS 1.1.19 ippAddCollection()

Description

Add a collection value.

Syntax

ipp_attribute_t *
ippAddCollection( ipp_t * ipp, ipp_tag_t group, const char * name, ipp_t * value);

Arguments

Returns

New attribute

 CUPS 1.1.19 ippAddCollections()

Description

Add an array of collection values.

Syntax

ipp_attribute_t *
ippAddCollections( ipp_t * ipp, ipp_tag_t group, const char * name, int num_values, const ipp_t ** values);

Arguments

Returns

New attribute

ippAddDate()

Description

Add a date attribute to an IPP message.

Syntax

ipp_attribute_t *
ippAddDate( ipp_t * ipp, ipp_tag_t group, const char * name, const ipp_uchar_t * value);

Arguments

Returns

New attribute

ippAddInteger()

Description

Add a integer attribute to an IPP message.

Syntax

ipp_attribute_t *
ippAddInteger( ipp_t * ipp, ipp_tag_t group, ipp_tag_t type, const char * name, int value);

Arguments

Returns

New attribute

ippAddIntegers()

Description

Add an array of integer values.

Syntax

ipp_attribute_t *
ippAddIntegers( ipp_t * ipp, ipp_tag_t group, ipp_tag_t type, const char * name, int num_values, const int * values);

Arguments

Returns

New attribute

 CUPS 1.2 ippAddOctetString()

Description

Add an octetString value to an IPP message.

Syntax

ipp_attribute_t *
ippAddOctetString( ipp_t * ipp, ipp_tag_t group, const char * name, const void * data, int datalen);

Arguments

Returns

New attribute

ippAddRange()

Description

Add a range of values to an IPP message.

Syntax

ipp_attribute_t *
ippAddRange( ipp_t * ipp, ipp_tag_t group, const char * name, int lower, int upper);

Arguments

Returns

New attribute

ippAddRanges()

Description

Add ranges of values to an IPP message.

Syntax

ipp_attribute_t *
ippAddRanges( ipp_t * ipp, ipp_tag_t group, const char * name, int num_values, const int * lower, const int * upper);

Arguments

Returns

New attribute

ippAddResolution()

Description

Add a resolution value to an IPP message.

Syntax

ipp_attribute_t *
ippAddResolution( ipp_t * ipp, ipp_tag_t group, const char * name, ipp_res_t units, int xres, int yres);

Arguments

Returns

New attribute

ippAddResolutions()

Description

Add resolution values to an IPP message.

Syntax

ipp_attribute_t *
ippAddResolutions( ipp_t * ipp, ipp_tag_t group, const char * name, int num_values, ipp_res_t units, const int * xres, const int * yres);

Arguments

Returns

New attribute

ippAddSeparator()

Description

Add a group separator to an IPP message.

Syntax

ipp_attribute_t *
ippAddSeparator( ipp_t * ipp);

Arguments

Returns

New attribute

ippAddString()

Description

Add a language-encoded string to an IPP message.

Syntax

ipp_attribute_t *
ippAddString( ipp_t * ipp, ipp_tag_t group, ipp_tag_t type, const char * name, const char * charset, const char * value);

Arguments

Returns

New attribute

ippAddStrings()

Description

Add language-encoded strings to an IPP message.

Syntax

ipp_attribute_t *
ippAddStrings( ipp_t * ipp, ipp_tag_t group, ipp_tag_t type, const char * name, int num_values, const char * charset, const char *const * values);

Arguments

Returns

New attribute

ippDateToTime()

Description

Convert from RFC 1903 Date/Time format to UNIX time in seconds.

Syntax

time_t
ippDateToTime( const ipp_uchar_t * date);

Arguments

Returns

UNIX time value

ippDelete()

Description

Delete an IPP message.

Syntax

void
ippDelete( ipp_t * ipp);

Arguments

Returns

Nothing.

 CUPS 1.1.19 ippDeleteAttribute()

Description

Delete a single attribute in an IPP message.

Syntax

void
ippDeleteAttribute( ipp_t * ipp, ipp_attribute_t * attr);

Arguments

Returns

Nothing.

ippErrorString()

Description

Return a name for the given status code.

Syntax

const char *
ippErrorString( ipp_status_t error);

Arguments

Returns

Text string

 CUPS 1.2 ippErrorValue()

Description

Return a status code for the given name.

Syntax

ipp_status_t
ippErrorValue( const char * name);

Arguments

Returns

IPP status code

ippFindAttribute()

Description

Find a named attribute in a request...

Syntax

ipp_attribute_t *
ippFindAttribute( ipp_t * ipp, const char * name, ipp_tag_t type);

Arguments

Returns

Matching attribute

ippFindNextAttribute()

Description

Find the next named attribute in a request...

Syntax

ipp_attribute_t *
ippFindNextAttribute( ipp_t * ipp, const char * name, ipp_tag_t type);

Arguments

Returns

Matching attribute

ippLength()

Description

Compute the length of an IPP message.

Syntax

size_t
ippLength( ipp_t * ipp);

Arguments

Returns

Size of IPP message

ippNew()

Description

Allocate a new IPP message.

Syntax

ipp_t *
ippNew(void);

Arguments

None.

Returns

New IPP message

 CUPS 1.2 ippNewRequest()

Description

Allocate a new IPP request message.

The new request message is initialized with the attributes-charset and attributes-natural-language attributes added. The attributes-natural-language value is derived from the current locale.

Syntax

ipp_t *
ippNewRequest( ipp_op_t op);

Arguments

Returns

IPP request message

 CUPS 1.2 ippOpString()

Description

Return a name for the given operation id.

Syntax

const char *
ippOpString( ipp_op_t op);

Arguments

Returns

Name

 CUPS 1.2 ippOpValue()

Description

Return an operation id for the given name.

Syntax

ipp_op_t
ippOpValue( const char * name);

Arguments

Returns

Operation ID

ippPort()

Description

Return the default IPP port number.

Syntax

int
ippPort(void);

Arguments

None.

Returns

Port number

ippRead()

Description

Read data for an IPP message from a HTTP connection.

Syntax

ipp_state_t
ippRead( http_t * http, ipp_t * ipp);

Arguments

Returns

Current state

 CUPS 1.1.19 ippReadFile()

Description

Read data for an IPP message from a file.

Syntax

ipp_state_t
ippReadFile( int fd, ipp_t * ipp);

Arguments

Returns

Current state

 CUPS 1.2 ippReadIO()

Description

Read data for an IPP message.

Syntax

ipp_state_t
ippReadIO( void * src, ipp_iocb_t cb, int blocking, ipp_t * parent, ipp_t * ipp);

Arguments

Returns

Current state

ippSetPort()

Description

Set the default port number.

Syntax

void
ippSetPort( int p);

Arguments

Returns

Nothing.

ippTimeToDate()

Description

Convert from UNIX time to RFC 1903 format.

Syntax

const ipp_uchar_t *
ippTimeToDate( time_t t);

Arguments

Returns

RFC-1903 date/time data

ippWrite()

Description

Write data for an IPP message to a HTTP connection.

Syntax

ipp_state_t
ippWrite( http_t * http, ipp_t * ipp);

Arguments

Returns

Current state

 CUPS 1.1.19 ippWriteFile()

Description

Write data for an IPP message to a file.

Syntax

ipp_state_t
ippWriteFile( int fd, ipp_t * ipp);

Arguments

Returns

Current state

 CUPS 1.2 ippWriteIO()

Description

Write data for an IPP message.

Syntax

ipp_state_t
ippWriteIO( void * dst, ipp_iocb_t cb, int blocking, ipp_t * parent, ipp_t * ipp);

Arguments

Returns

Current state

Structures

• http_addrlist_s  CUPS 1.2 
• ipp_attribute_s
• ipp_s

 CUPS 1.2 http_addrlist_s

Description

Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.

Definition

struct http_addrlist_s
{
  http_addr_t addr;
  struct http_addrlist_s * next;
};

Members

ipp_attribute_s

Description

Attribute

Definition

struct ipp_attribute_s
{
  char * name;
  struct ipp_attribute_s * next;
  int num_values;
  ipp_tag_t group_tag, value_tag;
  ipp_value_t values[1];
};

Members

ipp_s

Description

IPP Request/Response/Notification

Definition

struct ipp_s
{
  ipp_attribute_t * attrs;
  ipp_attribute_t * current;
  ipp_tag_t curtag;
  ipp_attribute_t * last;
  ipp_attribute_t * prev;
  ipp_request_t request;
  ipp_state_t state;
};

Members

Types

• http_addrlist_t  CUPS 1.2 
• http_auth_t
• http_encoding_t
• http_encryption_t
• http_t
• ipp_attribute_t
• ipp_iocb_t  CUPS 1.2 
• ipp_request_t
• ipp_t
• ipp_uchar_t
• ipp_value_t

 CUPS 1.2 http_addrlist_t

Description

Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.

Definition

typedef struct http_addrlist_s / http_addrlist_t;

http_auth_t

Description

HTTP authentication types

Definition

typedef enum http_auth_e http_auth_t;

http_encoding_t

Description

HTTP transfer encoding values

Definition

typedef enum http_encoding_e http_encoding_t;

http_encryption_t

Description

HTTP encryption values

Definition

typedef enum http_encryption_e http_encryption_t;

http_t

Description

HTTP connection type

Definition

typedef struct _http_s http_t;

ipp_attribute_t

Description

Attribute

Definition

typedef struct ipp_attribute_s ipp_attribute_t;

 CUPS 1.2 ipp_iocb_t

Description

IPP IO Callback Function

Definition

typedef ssize_t (*ipp_iocb_t)(void *, ipp_uchar_t *, size_t);

ipp_request_t

Description

Request Header

Definition

typedef union ipp_request_u ipp_request_t;

ipp_t

Description

Attribute Value

Definition

typedef struct ipp_s ipp_t;

ipp_uchar_t

Description

IPP status codes...

Definition

typedef typedef unsigned char ipp_uchar_t;

ipp_value_t

Description

New in CUPS 1.1.19

Definition

typedef union ipp_value_u ipp_value_t;

Unions

• ipp_request_u
• ipp_value_u

ipp_request_u

Description

Request Header

Definition

union ipp_request_u
{
};

Members

ipp_value_u

Description

New in CUPS 1.1.19

Definition

union ipp_value_u
{
  char boolean;
  ipp_t * collection;
  ipp_uchar_t date[11];
  int integer;
};

Members