HTTP and IPP APIs
Keywords: Programming

## 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_status_e`
- `ipp_res_e`
- `ipp_status_e`
- `ipp_tag_e`

### http_auth_e

#### Description

HTTP authentication types

#### Values

Name | Description
--- | ---
`HTTP_AUTH_BASIC` | Basic authentication in use
`HTTP_AUTH_MD5` | Digest authentication in use
`HTTP_AUTH_MD5_INT` | Digest authentication in use for body
`HTTP_AUTH_MD5_SESS` | MD5-session authentication in use
`HTTP_AUTH_MD5_SESS_INT` | MD5-session authentication in use for body
`HTTP_AUTH_NONE` | No authentication in use

### http_encoding_e

#### Description

HTTP transfer encoding values

#### Values

Name | Description
--- | ---
`HTTP_ENCODE_CHUNKED` | Data is chunked
`HTTP_ENCODE_LENGTH` | Data is sent with Content-Length

### http_encryption_e

#### Description

HTTP encryption values

#### Values

Name | Description
--- | ---
`HTTP_ENCRYPT_ALWAYS` | Always encrypt (SSL)
`HTTP_ENCRYPT_IF_REQUESTED` | Encrypt if requested (TLS upgrade)
`HTTP_ENCRYPT_NEVER` | Never encrypt
`HTTP_ENCRYPT_REQUIRED` | Encryption is required (TLS upgrade)

### http_field_e

#### Description

HTTP field names

#### Values

Name | Description
--- | ---
`HTTP_FIELD_ACCEPT_LANGUAGE` | Accept-Language field
`HTTP_FIELD_ACCEPT_RANGES` | Accept-Ranges field
`HTTP_FIELD_AUTHORIZATION` | Authorization field
`HTTP_FIELD_CONNECTION` | Connection field
`HTTP_FIELD_CONTENT_ENCODING` | Content-Encoding field
`HTTP_FIELD_CONTENT_LANGUAGE` | Content-Language field
`HTTP_FIELD_CONTENT_LENGTH` | Content-Length field
`HTTP_FIELD_CONTENT_LOCATION` | Content-Location field
`HTTP_FIELD_CONTENT_MD5` | Content-MD5 field
`HTTP_FIELD_CONTENT_RANGE` | Content-Range field
`HTTP_FIELD_CONTENT_TYPE` | Content-Type field
`HTTP_FIELD_CONTENT_VERSION` | Content-Version field
`HTTP_FIELD_DATE` | Date field
`HTTP_FIELD_HOST` | Host field
`HTTP_FIELD_IF_MODIFIED_SINCE` | If-Modified-Since field
`HTTP_FIELD_IF_UNMODIFIED_SINCE` | If-Unmodified-Since field
`HTTP_FIELD_KEEP_ALIVE` | Keep-Alive field
`HTTP_FIELD_LAST_MODIFIED` | Last-Modified field
`HTTP_FIELD_LINK` | Link field
`HTTP_FIELD_LOCATION` | Location field
`HTTP_FIELD_MAX` | Maximum field index
`HTTP_FIELD_RANGE` | Range field
`HTTP_FIELD_REFERER` | Referer field
`HTTP_FIELD_RETRY_AFTER` | Retry-After field
`HTTP_FIELD_TRANSFER_ENCODING` | Transfer-Encoding field
`HTTP_FIELD_UNKNOWN` | Unknown field
`HTTP_FIELD_UPGRADE` | Upgrade field
`HTTP_FIELD_USER_AGENT` | User-Agent field
`HTTP_FIELD_WWW_AUTHENTICATE` | WWW-Authenticate field

### http_keepalive_e

#### Description

Types and structures...

#### Values

Name | Description
--- | ---
`HTTP_KEEPALIVE_OFF` | No keep alive support
`HTTP_KEEPALIVE_ON` | Use keep alive

### http_status_e

#### Description

HTTP status codes

#### Values

Name | Description
--- | ---
`HTTP_ACCEPTED` | DELETE command was successful
`HTTP_BAD_GATEWAY` | Bad gateway
`HTTP_BAD_REQUEST` | Bad request
`HTTP_CONFLICT` | Request is self-conflicting
`HTTP_CONTINUE` | Everything OK, keep going...
`HTTP_CREATED` | PUT command was successful
`HTTP_ERROR` | An error response from httpXxxx()
`HTTP_EXPECTATION_FAILED` | The expectation given in an Expect header field was not met
`HTTP_FORBIDDEN` | Forbidden to access this URI
`HTTP_GATEWAY_TIMEOUT` | Gateway connection timed out
`HTTP_GONE` | Server has gone away
`HTTP_LENGTH_REQUIRED` | A content length or encoding is required
`HTTP_METHOD_NOT_ALLOWED` | Method is not allowed
`HTTP_MOVED_PERMANENTLY` | Document has moved permanently
`HTTP_MOVED_TEMPORARILY` | Document has moved temporarily
`HTTP_MULTIPLE_CHOICES` | Multiple files match request
`HTTP_NOT_ACCEPTABLE` | Not Acceptable
`HTTP_NOT_AUTHORITATIVE` | Information isn't authoritative
`HTTP_NOT_FOUND` | URI was not found
`HTTP_NOT_IMPLEMENTED` | Feature not implemented
`HTTP_NOT_MODIFIED` | File not modified
`HTTP_NOT_SUPPORTED` | HTTP version not supported
`HTTP_NO_CONTENT` | Successful command, no new data
`HTTP_OK` | OPTIONS/GET/HEAD/POST/TRACE command was successful
`HTTP_PARTIAL_CONTENT` | Only a partial file was recieved/sent
`HTTP_PAYMENT_REQUIRED` | Payment required
`HTTP_PRECONDITION` | Precondition failed
`HTTP_PROXY_AUTHENTICATION` | Proxy Authentication is Required
`HTTP_REQUESTED_RANGE` | The requested range is not satisfiable
`HTTP_REQUEST_TIMEOUT` | Request timed out
`HTTP_REQUEST_TOO_LARGE` | Request entity too large
`HTTP_RESET_CONTENT` | Content was reset/recreated
`HTTP_SEE_OTHER` | See this other link...
`HTTP_SERVER_ERROR` | Internal server error
`HTTP_SERVICE_UNAVAILABLE` | Service is unavailable
`HTTP_SWITCHING_PROTOCOLS` | HTTP upgrade to TLS/SSL
`HTTP_UNAUTHORIZED` | Unauthorized to access host
`HTTP_UNSUPPORTED_MEDIATYPE` | The requested media type is unsupported
`HTTP_UPGRADE_REQUIRED` | Upgrade to SSL/TLS required
`HTTP_URI_TOO_LONG` | URI too long
`HTTP_USE_PROXY` | Must use a proxy to access this URI

### ipp_res_e

#### Description

Types and structures...

#### Values

Name | Description
--- | ---
`IPP_RES_PER_CM` | Pixels per centimeter
`IPP_RES_PER_INCH` | Pixels per inch

### ipp_status_e

#### Description

IPP status codes...

#### Values

Name | Description
--- | ---
`IPP_ATTRIBUTES` | client-error-attributes-or-values-not-supported
`IPP_ATTRIBUTES_NOT_SETTABLE` | client-error-attributes-not-settable
`IPP_BAD_REQUEST` | client-error-bad-request
`IPP_CHARSET` | client-error-charset-not-supported
`IPP_COMPRESSION_ERROR` | client-error-compression-error
`IPP_COMPRESSION_NOT_SUPPORTED` | client-error-compression-not-supported
`IPP_CONFLICT` | client-error-conflicting-attributes
`IPP_DEVICE_ERROR` | server-error-device-error
`IPP_DOCUMENT_ACCESS_ERROR` | client-error-document-access-error
`IPP_DOCUMENT_FORMAT` | client-error-document-format-not-supported
`IPP_DOCUMENT_FORMAT_ERROR` | client-error-document-format-error
`IPP_ERROR_JOB_CANCELLED` | server-error-job-canceled
`IPP_FORBIDDEN` | client-error-forbidden
`IPP_GONE` | client-error-gone
`IPP_IGNORED_ALL_NOTIFICATIONS` | client-error-ignored-all-notifications
`IPP_IGNORED_ALL_SUBSCRIPTIONS` | client-error-ignored-all-subscriptions
`IPP_INTERNAL_ERROR` | server-error-internal-error
`IPP_MULTIPLE_JOBS_NOT_SUPPORTED` | server-error-multiple-document-jobs-not-supported
`IPP_NOT_ACCEPTING` | server-error-not-accepting-jobs
`IPP_NOT_AUTHENTICATED` | client-error-not-authenticated
`IPP_NOT_AUTHORIZED` | client-error-not-authorized
`IPP_NOT_FOUND` | client-error-not-found
`IPP_NOT_POSSIBLE` | client-error-not-possible
`IPP_OK` | successful-ok
`IPP_OK_BUT_CANCEL_SUBSCRIPTION` | successful-ok-but-cancel-subscription
`IPP_OK_CONFLICT` | successful-ok-conflicting-attributes
`IPP_OK_EVENTS_COMPLETE` | successful-ok-events-complete
`IPP_OK_IGNORED_NOTIFICATIONS` | successful-ok-ignored-notifications
`IPP_OK_IGNORED_SUBSCRIPTIONS` | successful-ok-ignored-subscriptions
`IPP_OK_SUBST` | successful-ok-ignored-or-substituted-attributes
`IPP_OK_TOO_MANY_EVENTS` | successful-ok-too-many-events
`IPP_OPERATION_NOT_SUPPORTED` | server-error-operation-not-supported
`IPP_PRINTER_BUSY` | server-error-busy
`IPP_PRINTER_IS_DEACTIVATED` | server-error-printer-is-deactivated
`IPP_PRINT_SUPPORT_FILE_NOT_FOUND` | client-error-print-support-file-not-found
`IPP_REDIRECTION_OTHER_SITE` |
`IPP_REQUEST_ENTITY` | client-error-request-entity-too-large
`IPP_REQUEST_VALUE` | client-error-request-value-too-long
`IPP_SERVICE_UNAVAILABLE` | server-error-service-unavailable
`IPP_TEMPORARY_ERROR` | server-error-temporary-error
`IPP_TIMEOUT` | client-error-timeout
`IPP_TOO_MANY_SUBSCRIPTIONS` | client-error-too-many-subscriptions
`IPP_URI_SCHEME` | client-error-uri-scheme-not-supported
`IPP_VERSION_NOT_SUPPORTED` | server-error-version-not-supported

### ipp_tag_e

#### Description

Format tags for attributes...

#### Values

Name | Description
--- | ---
`IPP_TAG_ADMINDEFINE` | Admin-defined value
`IPP_TAG_BEGIN_COLLECTION` | Beginning of collection value
`IPP_TAG_BOOLEAN` | Boolean value
`IPP_TAG_CHARSET` | Character set value
`IPP_TAG_COPY` | Bitflag for copied attribute values
`IPP_TAG_DATE` | Date/time value
`IPP_TAG_DEFAULT` | Default value
`IPP_TAG_DELETEATTR` | Delete-attribute value
`IPP_TAG_END` | End-of-attributes
`IPP_TAG_END_COLLECTION` | End of collection value
`IPP_TAG_ENUM` | Enumeration value
`IPP_TAG_EVENT_NOTIFICATION` | Event group
`IPP_TAG_INTEGER` | Integer value
`IPP_TAG_JOB` | Job group
`IPP_TAG_KEYWORD` | Keyword value
`IPP_TAG_LANGUAGE` | Language value
`IPP_TAG_MASK` | Mask for copied attribute values
`IPP_TAG_MEMBERNAME` | Collection member name value
`IPP_TAG_MIMETYPE` | MIME media type value
`IPP_TAG_NAME` | Name value
`IPP_TAG_NAMELANG` | Name-with-language value
`IPP_TAG_NOTSETTABLE` | Not-settable value
`IPP_TAG_NOVALUE` | No-value value
`IPP_TAG_OPERATION` | Operation group
`IPP_TAG_PRINTER` | Printer group
`IPP_TAG_RANGE` | Range value
`IPP_TAG_RESOLUTION` | Resolution value
`IPP_TAG_STRING` | Octet string value
`IPP_TAG_SUBSCRIPTION` | Subscription group
`IPP_TAG_TEXT` | Text value
`IPP_TAG_TEXTLANG` | Text-with-language value
`IPP_TAG_UNKNOWN` | Unknown value
`IPP_TAG_UNSUPPORTED_GROUP` | Unsupported attributes group
`IPP_TAG_UNSUPPORTED_VALUE` | Unsupported value
`IPP_TAG_URI` | URI value
`IPP_TAG_URISCHEME` | URI scheme value
`IPP_TAG_ZERO` | Zero tag - used for separators

## Functions

- `cupsDoAuthentication()` CUPS 1.1.20
- `cupsDoFileRequest()`
- `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()`
- `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
- `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

Name | Description
--- | ---
`http` | HTTP connection to server
`method` | Request method (GET, POST, PUT)
`resource` | Resource path

#### 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

Name | Description
--- | ---
`http` | HTTP connection to server
`request` | IPP request
`resource` | HTTP resource for POST
`filename` | File to send or NULL for none

#### 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

Name | Description
--- | ---
`http` | HTTP connection to server
`request` | IPP request
`resource` | HTTP resource for POST

#### 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

Name | Description
--- | ---
`ipp` | Request to add to
`num_options` | Number of options
`options` | Options

#### 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

Name | Description
--- | ---
`ipp` | Request to add to
`num_options` | Number of options
`options` | Options
`group_tag` | Group to encode

#### Returns

Nothing.

### CUPS 1.2 httpAddrAny()

#### Description

Check for the "any" address.

#### Syntax

    int
    httpAddrAny(
        const http_addr_t * addr);

#### Arguments

Name | Description
--- | ---
`addr` | Address to check

#### 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

Name | Description
--- | ---
`addr1` | First address
`addr2` | Second address

#### 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

Name | Description
--- | ---
`addr` | Address

#### Returns

Length in bytes

### CUPS 1.2 httpAddrLocalhost()

#### Description

Check for the local loopback address.

#### Syntax

    int
    httpAddrLocalhost(
        const http_addr_t * addr);

#### Arguments

Name | Description
--- | ---
`addr` | Address to check

#### 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

Name | Description
--- | ---
`addr` | Address to lookup
`name` | Host name buffer
`namelen` | Size of name buffer

#### 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

Name | Description
--- | ---
`addr` | Address to convert
`s` | String buffer
`slen` | Length of string

#### 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

Name | Description
--- | ---
`encoding` | Encoding flags
`uri` | URI buffer
`urilen` | Size of URI buffer
`scheme` | Scheme name
`username` | Username
`host` | Hostname or address
`port` | Port number
`resource` | Resource

#### 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

Name | Description
--- | ---
`encoding` | Encoding flags
`uri` | URI buffer
`urilen` | Size of URI buffer
`scheme` | Scheme name
`username` | Username
`host` | Hostname or address
`port` | Port number
`resourcef` | Printf-style resource
`...` | Additional arguments as needed

#### Returns

URI status

### httpBlocking()

#### Description

Set blocking/non-blocking behavior on a connection.

#### Syntax

    void
    httpBlocking(
        http_t * http,
        int b);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`b` | 1 = blocking, 0 = non-blocking

#### Returns

Nothing.

### httpCheck()

#### Description

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

#### Syntax

    int
    httpCheck(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection

#### Returns

Nothing.

### httpClearFields()

#### Description

Clear HTTP request fields.

#### Syntax

    void
    httpClearFields(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### Returns

Nothing.

### httpClose()

#### Description

Close an HTTP connection...

#### Syntax

    void
    httpClose(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### Returns

Nothing.

### httpConnect()

#### Description

Connect to a HTTP server.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`host` | Host to connect to
`port` | Port number

#### 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

Name | Description
--- | ---
`host` | Host to connect to
`port` | Port number
`encryption` | Type of encryption to use

#### 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

Name | Description
--- | ---
`out` | String to write to
`in` | String to read from

#### 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

Name | Description
--- | ---
`out` | String to write to
`outlen` | Size of output string
`in` | String to read from

#### Returns

Decoded string

### httpDelete()

#### Description

Send a DELETE request to the server.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI to delete

#### 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

Name | Description
--- | ---
`out` | String to write to
`in` | String to read from

#### 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

Name | Description
--- | ---
`out` | String to write to
`outlen` | Size of output string
`in` | String to read from
`inlen` | Size of input string

#### Returns

Encoded string

### httpEncryption()

#### Description

Set the required encryption on the link.

#### Syntax

    int
    httpEncryption(
        http_t * http,
        http_encryption_t e);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`e` | New encryption preference

#### Returns

-1 on error, 0 on success

### httpError()

#### Description

Get the last error on a connection.

#### Syntax

    int
    httpError(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### Returns

Error code (errno) value

### httpFlush()

#### Description

Flush data from a HTTP connection.

#### Syntax

    void
    httpFlush(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### Returns

Nothing.

### CUPS 1.2 httpFlushWrite()

#### Description

Flush data in write buffer.

#### Syntax

    int
    httpFlushWrite(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI to get

#### Returns

Status of call (0 = success)

### CUPS 1.2 httpGetBlocking()

#### Description

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

#### Syntax

    int
    httpGetBlocking(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connecion

#### 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

Name | Description
--- | ---
`t` | UNIX time

#### 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

Name | Description
--- | ---
`t` | UNIX time
`s` | String buffer
`slen` | Size of string buffer

#### Returns

Date/time string

### httpGetDateTime()

#### Description

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

#### Syntax

    time_t
    httpGetDateTime(
        const char * s);

#### Arguments

Name | Description
--- | ---
`s` | Date/time string

#### Returns

UNIX time

### CUPS 1.2 httpGetFd()

#### Description

Get the file descriptor associated with a connection.

#### Syntax

    int
    httpGetFd(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`field` | Field to get

#### 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

Name | Description
--- | ---
`name` | Hostname or IP address

#### 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

Name | Description
--- | ---
`http` | HTTP connection or NULL
`s` | String buffer for name
`slen` | Size of buffer

#### 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

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`field` | Field index
`name` | Name of sub-field
`value` | Value string

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`field` | Field index
`name` | Name of sub-field
`value` | Value string
`valuelen` | Size of value buffer

#### 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

Name | Description
--- | ---
`line` | Line to read into
`length` | Max length of buffer
`http` | HTTP connection

#### Returns

Line or NULL

### httpHead()

#### Description

Send a HEAD request to the server.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI for head

#### 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

Name | Description
--- | ---
`username` | User name
`realm` | Realm name
`passwd` | Password string
`md5[33]` | MD5 string

#### 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

Name | Description
--- | ---
`nonce` | Server nonce value
`method` | METHOD (GET, POST, etc.)
`resource` | Resource path
`md5[33]` | MD5 sum

#### Returns

New sum

### httpMD5String()

#### Description

Convert an MD5 sum to a character string.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`sum` | MD5 sum data
`md5[33]` | MD5 sum in hex

#### Returns

MD5 sum in hex

### httpOptions()

#### Description

Send an OPTIONS request to the server.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI for options

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI for post

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI to put

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`buffer` | Buffer for data
`length` | Maximum number of bytes

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`buffer` | Buffer for data
`length` | Maximum number of bytes

#### Returns

Number of bytes read

### httpReconnect()

#### Description

Reconnect to a HTTP server.

#### Syntax

    int
    httpReconnect(
        http_t * http);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`uri` | Universal Resource Identifier
`scheme` | Scheme [32] (http, https, etc.)
`username` | Username [1024]
`host` | Hostname [1024]
`port` | Port number to use
`resource` | Resource/filename [1024]

#### 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

Name | Description
--- | ---
`uri` | Universal Resource Identifier
`scheme` | Scheme (http, https, etc.)
`schemelen` | Size of scheme buffer
`username` | Username
`usernamelen` | Size of username buffer
`host` | Hostname
`hostlen` | Size of hostname buffer
`port` | Port number to use
`resource` | Resource/filename
`resourcelen` | Size of resource buffer

#### 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

Name | Description
--- | ---
`decoding` | Decoding flags
`uri` | Universal Resource Identifier
`scheme` | Scheme (http, https, etc.)
`schemelen` | Size of scheme buffer
`username` | Username
`usernamelen` | Size of username buffer
`host` | Hostname
`hostlen` | Size of hostname buffer
`port` | Port number to use
`resource` | Resource/filename
`resourcelen` | Size of resource buffer

#### Returns

Result of separation

### CUPS 1.1.19 httpSetCookie()

#### Description

Set the cookie value(s)...

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`http` | Connection
`cookie` | Cookie string

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`expect` | HTTP status to expect (HTTP_CONTINUE)

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`field` | Field index
`value` | Value

#### Returns

Nothing.

### CUPS 1.2 httpSetLength()

#### Description

Set the content-length and content-encoding.

#### Syntax

    void
    httpSetLength(
        http_t * http,
        size_t length);

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`length` | Length (0 for chunked)

#### Returns

Nothing.

### httpStatus()

#### Description

Return a short string describing a HTTP status code.

#### Syntax

    const char *
    httpStatus(
        http_status_t status);

#### Arguments

Name | Description
--- | ---
`status` | HTTP status code

#### Returns

String or NULL

### httpTrace()

#### Description

Send an TRACE request to the server.

#### Syntax

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

#### Arguments

Name | Description
--- | ---
`http` | HTTP connection
`uri` | URI for trace

#### 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

Name | Description
--- | ---
`http` | HTTP connection

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`msec` | Milliseconds to wait

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`buffer` | Buffer for data
`length` | Number of bytes to write

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`buffer` | Buffer for data
`length` | Number of bytes to write

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`value` | Value of attribute

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`num_values` | Number of values
`values` | Values

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`value` | Value

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`num_values` | Number of values
`values` | Values

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`value` | Value

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`type` | Type of attribute
`name` | Name of attribute
`value` | Value of attribute

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`type` | Type of attribute
`name` | Name of attribute
`num_values` | Number of values
`values` | Values

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`data` | octetString data
`datalen` | Length of data in bytes

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`lower` | Lower value
`upper` | Upper value

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`num_values` | Number of values
`lower` | Lower values
`upper` | Upper values

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`units` | Units for resolution
`xres` | X resolution
`yres` | Y resolution

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`name` | Name of attribute
`num_values` | Number of values
`units` | Units for resolution
`xres` | X resolutions
`yres` | Y resolutions

#### Returns

New attribute

### ippAddSeparator()

#### Description

Add a group separator to an IPP message.

#### Syntax

    ipp_attribute_t *
    ippAddSeparator(
        ipp_t * ipp);

#### Arguments

Name | Description
--- | ---
`ipp` | IPP message

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`type` | Type of attribute
`name` | Name of attribute
`charset` | Character set
`value` | Value

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`group` | IPP group
`type` | Type of attribute
`name` | Name of attribute
`num_values` | Number of values
`charset` | Character set
`values` | Values

#### 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

Name | Description
--- | ---
`date` | RFC 1903 date info

#### Returns

UNIX time value

### ippDelete()

#### Description

Delete an IPP message.

#### Syntax

    void
    ippDelete(
        ipp_t * ipp);

#### Arguments

Name | Description
--- | ---
`ipp` | IPP message

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`attr` | Attribute to delete

#### Returns

Nothing.

### ippErrorString()

#### Description

Return a name for the given status code.

#### Syntax

    const char *
    ippErrorString(
        ipp_status_t error);

#### Arguments

Name | Description
--- | ---
`error` | Error status

#### 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

Name | Description
--- | ---
`name` | Name

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`name` | Name of attribute
`type` | Type of attribute

#### 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

Name | Description
--- | ---
`ipp` | IPP message
`name` | Name of attribute
`type` | Type of attribute

#### Returns

Matching attribute

### ippLength()

#### Description

Compute the length of an IPP message.

#### Syntax

    size_t
    ippLength(
        ipp_t * ipp);

#### Arguments

Name | Description
--- | ---
`ipp` | IPP message

#### 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

Name | Description
--- | ---
`op` | Operation code

#### 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

Name | Description
--- | ---
`op` | Operation ID

#### Returns

Name

### CUPS 1.2 ippOpValue()

#### Description

Return an operation id for the given name.

#### Syntax

    ipp_op_t
    ippOpValue(
        const char * name);

#### Arguments

Name | Description
--- | ---
`name` | Textual name

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`ipp` | IPP data

#### 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

Name | Description
--- | ---
`fd` | HTTP data
`ipp` | IPP data

#### 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

Name | Description
--- | ---
`src` | Data source
`cb` | Read callback function
`blocking` | Use blocking IO?
`parent` | Parent request, if any
`ipp` | IPP data

#### Returns

Current state

### ippSetPort()

#### Description

Set the default port number.

#### Syntax

    void
    ippSetPort(
        int p);

#### Arguments

Name | Description
--- | ---
`p` | Port number to use

#### Returns

Nothing.

### ippTimeToDate()

#### Description

Convert from UNIX time to RFC 1903 format.

#### Syntax

    const ipp_uchar_t *
    ippTimeToDate(
        time_t t);

#### Arguments

Name | Description
--- | ---
`t` | UNIX time value

#### 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

Name | Description
--- | ---
`http` | HTTP connection
`ipp` | IPP data

#### 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

Name | Description
--- | ---
`fd` | HTTP data
`ipp` | IPP data

#### 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

Name | Description
--- | ---
`dst` | Destination
`cb` | Write callback function
`blocking` | Use blocking IO?
`parent` | Parent IPP message
`ipp` | IPP data

#### 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

Name | Description
--- | ---
`addr` | Address
`next` | Pointer to next address in list

### 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

Name | Description
--- | ---
`name` | Name of attribute
`next` | Next attribute in list
`num_values` | Number of values
`value_tag` | What type of value is it?
`values[1]` | Values

### 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

Name | Description
--- | ---
`attrs` | Attributes
`current` | Current attribute (for read/write)
`curtag` | Current attribute group tag
`last` | Last attribute in list
`prev` | Previous attribute (for read)
`request` | Request header
`state` | State of request

## 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 structure.

#### 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

Name | Description
--- | ---

### 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

Name | Description
--- | ---
`boolean` | Boolean value
`collection` | Collection value
`date[11]` | Date/time value
`integer` | Integer/enumerated value