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

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_NEGOTIATE` CUPS 1.3 | GSSAPI authentication in use
`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_FIELDS` | Sending HTTP fields
`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_state_e

#### Description

#### Values

Name | Description
--- | ---
`HTTP_CLOSE` | CLOSE command, waiting for blank line
`HTTP_DELETE` | DELETE command, waiting for blank line
`HTTP_GET` | GET command, waiting for blank line
`HTTP_GET_SEND` | GET command, sending data
`HTTP_HEAD` | HEAD command, waiting for blank line
`HTTP_OPTIONS` | OPTIONS command, waiting for blank line
`HTTP_POST` | POST command, waiting for blank line
`HTTP_POST_RECV` | POST command, receiving data
`HTTP_POST_SEND` | POST command, sending data
`HTTP_PUT` | PUT command, waiting for blank line
`HTTP_PUT_RECV` | PUT command, receiving data
`HTTP_STATUS` | Command complete, sending status
`HTTP_TRACE` | TRACE command, waiting for blank line
`HTTP_WAITING` | Waiting for command

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

### http_uri_coding_e

#### Description

#### Values

Name | Description
--- | ---
`HTTP_URI_CODING_ALL` | En/decode everything
`HTTP_URI_CODING_HOSTNAME` | En/decode the hostname portion
`HTTP_URI_CODING_MOST` | En/decode all but the query
`HTTP_URI_CODING_NONE` | Don't en/decode anything
`HTTP_URI_CODING_QUERY` | En/decode the query portion
`HTTP_URI_CODING_RESOURCE` | En/decode the resource portion
`HTTP_URI_CODING_USERNAME` | En/decode the username portion

### http_uri_status_e

#### Description

#### Values

Name | Description
--- | ---
`HTTP_URI_BAD_ARGUMENTS` | Bad arguments to function (error)
`HTTP_URI_BAD_HOSTNAME` | Bad hostname in URI (error)
`HTTP_URI_BAD_PORT` | Bad port number in URI (error)
`HTTP_URI_BAD_RESOURCE` | Bad resource in URI (error)
`HTTP_URI_BAD_SCHEME` | Bad scheme in URI (error)
`HTTP_URI_BAD_URI` | Bad/empty URI (error)
`HTTP_URI_BAD_USERNAME` | Bad username in URI (error)
`HTTP_URI_MISSING_RESOURCE` | Missing resource in URI (warning)
`HTTP_URI_MISSING_SCHEME` | Missing scheme in URI (warning)
`HTTP_URI_OK` | URI decoded OK
`HTTP_URI_OVERFLOW` | URI buffer for httpAssembleURI is too small
`HTTP_URI_UNKNOWN_SCHEME` | Unknown scheme in URI (warning)

### http_version_e

#### Description

#### Values

Name | Description
--- | ---
`HTTP_0_9` | HTTP/0.9
`HTTP_1_0` | HTTP/1.0
`HTTP_1_1` | HTTP/1.1

### ipp_finish_e

#### Description

#### Values

Name | Description
--- | ---
`IPP_FINISHINGS_BALE` | Bale (any type)
`IPP_FINISHINGS_BIND` | Bind
`IPP_FINISHINGS_BIND_BOTTOM` | Bind on bottom
`IPP_FINISHINGS_BIND_LEFT` | Bind on left
`IPP_FINISHINGS_BIND_RIGHT` | Bind on right
`IPP_FINISHINGS_BIND_TOP` | Bind on top
`IPP_FINISHINGS_BOOKLET_MAKER` | Fold to make booklet
`IPP_FINISHINGS_COVER` | Add cover
`IPP_FINISHINGS_EDGE_STITCH` | Stitch along any side
`IPP_FINISHINGS_EDGE_STITCH_BOTTOM` | Stitch along bottom edge
`IPP_FINISHINGS_EDGE_STITCH_LEFT` | Stitch along left side
`IPP_FINISHINGS_EDGE_STITCH_RIGHT` | Stitch along right side
`IPP_FINISHINGS_EDGE_STITCH_TOP` | Stitch along top edge
`IPP_FINISHINGS_FOLD` | Fold (any type)
`IPP_FINISHINGS_JOB_OFFSET` | Offset for binding (any type)
`IPP_FINISHINGS_NONE` | No finishing
`IPP_FINISHINGS_PUNCH` | Punch (any location/count)
`IPP_FINISHINGS_SADDLE_STITCH` | Staple interior
`IPP_FINISHINGS_STAPLE` | Staple (any location)
`IPP_FINISHINGS_STAPLE_BOTTOM_LEFT` | Staple bottom left corner
`IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT` | Staple bottom right corner
`IPP_FINISHINGS_STAPLE_DUAL_BOTTOM` | Two staples on bottom
`IPP_FINISHINGS_STAPLE_DUAL_LEFT` | Two staples on left
`IPP_FINISHINGS_STAPLE_DUAL_RIGHT` | Two staples on right
`IPP_FINISHINGS_STAPLE_DUAL_TOP` | Two staples on top
`IPP_FINISHINGS_STAPLE_TOP_LEFT` | Staple top left corner
`IPP_FINISHINGS_STAPLE_TOP_RIGHT` | Staple top right corner
`IPP_FINISHINGS_TRIM` | Trim (any type)

### ipp_jstate_e

#### Description

#### Values

Name | Description
--- | ---
`IPP_JOB_ABORTED` | Job has aborted due to error
`IPP_JOB_CANCELED` | Job has been canceled
`IPP_JOB_COMPLETED` | Job has completed successfully
`IPP_JOB_HELD` | Job is held for printing
`IPP_JOB_PENDING` | Job is waiting to be printed
`IPP_JOB_PROCESSING` | Job is currently printing
`IPP_JOB_STOPPED` | Job has been stopped

### ipp_op_e

#### Description

#### Values

Name | Description
--- | ---
`CUPS_ACCEPT_JOBS` | Accept new jobs on a printer
`CUPS_ADD_MODIFY_CLASS` | Add or modify a class
`CUPS_ADD_MODIFY_PRINTER` | Add or modify a printer
`CUPS_AUTHENTICATE_JOB` CUPS 1.2 | Authenticate a job
`CUPS_DELETE_CLASS` | Delete a class
`CUPS_DELETE_PRINTER` | Delete a printer
`CUPS_GET_CLASSES` DEPRECATED | Get a list of classes
`CUPS_GET_DEFAULT` | Get the default printer
`CUPS_GET_DEVICES` | Get a list of supported devices
`CUPS_GET_PPD` CUPS 1.3 | Get a PPD file
`CUPS_GET_PPDS` | Get a list of supported drivers
`CUPS_GET_PRINTERS` | Get a list of printers and/or classes
`CUPS_MOVE_JOB` | Move a job to a different printer
`CUPS_REJECT_JOBS` | Reject new jobs on a printer
`CUPS_SET_DEFAULT` | Set the default printer
`IPP_ACTIVATE_PRINTER` | Start a printer @private@
`IPP_CANCEL_CURRENT_JOB` | Cancel the current job @private@
`IPP_CANCEL_JOB` | Cancel a job
`IPP_CANCEL_SUBSCRIPTION` CUPS 1.2 | Cancel a subscription
`IPP_CREATE_JOB` | Create an empty print job
`IPP_CREATE_JOB_SUBSCRIPTION` CUPS 1.2 | Create a job subscription
`IPP_CREATE_PRINTER_SUBSCRIPTION` CUPS 1.2 | Create a printer subscription
`IPP_DEACTIVATE_PRINTER` | Stop a printer @private@
`IPP_DISABLE_PRINTER` | Stop a printer
`IPP_ENABLE_PRINTER` | Start a printer
`IPP_GET_JOBS` | Get a list of jobs
`IPP_GET_JOB_ATTRIBUTES` | Get job attributes
`IPP_GET_NOTIFICATIONS` CUPS 1.2 | Get notification events
`IPP_GET_PRINTER_ATTRIBUTES` | Get printer attributes
`IPP_GET_PRINTER_SUPPORTED_VALUES` | Get supported attribute values
`IPP_GET_PRINT_SUPPORT_FILES` | Get printer support files @private@
`IPP_GET_SUBSCRIPTIONS` CUPS 1.2 | Get list of subscriptions
`IPP_GET_SUBSCRIPTION_ATTRIBUTES` CUPS 1.2 | Get subscription attributes
`IPP_HOLD_JOB` | Hold a job for printing
`IPP_HOLD_NEW_JOBS` | Hold new jobs @private@
`IPP_PAUSE_PRINTER` | Stop a printer
`IPP_PAUSE_PRINTER_AFTER_CURRENT_JOB` | Stop printer after the current job @private@
`IPP_PRINT_JOB` | Print a single file
`IPP_PRINT_URI` | Print a single URL @private@
`IPP_PRIVATE` | Reserved @private@
`IPP_PROMOTE_JOB` | Promote a job to print sooner @private@
`IPP_PURGE_JOBS` | Cancel all jobs
`IPP_RELEASE_HELD_NEW_JOBS` | Release new jobs @private@
`IPP_RELEASE_JOB` | Release a job for printing
`IPP_RENEW_SUBSCRIPTION` CUPS 1.2 | Renew a printer subscription
`IPP_REPROCESS_JOB` | Reprint a job @private@
`IPP_RESTART_JOB` | Reprint a job
`IPP_RESTART_PRINTER` | Restart a printer @private@
`IPP_RESUME_JOB` | Resume the current job @private@
`IPP_RESUME_PRINTER` | Start a printer
`IPP_SCHEDULE_JOB_AFTER` | Schedule a job to print after another @private@
`IPP_SEND_DOCUMENT` | Add a file to a job
`IPP_SEND_NOTIFICATIONS` | Send notification events @private@
`IPP_SEND_URI` | Add a URL to a job @private@
`IPP_SET_JOB_ATTRIBUTES` | Set job attributes
`IPP_SET_PRINTER_ATTRIBUTES` | Set printer attributes @private@
`IPP_SHUTDOWN_PRINTER` | Turn a printer off @private@
`IPP_STARTUP_PRINTER` | Turn a printer on @private@
`IPP_SUSPEND_CURRENT_JOB` | Suspend the current job @private@
`IPP_VALIDATE_JOB` | Validate job options

### ipp_orient_e

#### Description

#### Values

Name | Description
--- | ---
`IPP_LANDSCAPE` | 90 degrees counter-clockwise
`IPP_PORTRAIT` | No rotation
`IPP_REVERSE_LANDSCAPE` | 90 degrees clockwise
`IPP_REVERSE_PORTRAIT` | 180 degrees

### ipp_pstate_e

#### Description

#### Values

Name | Description
--- | ---
`IPP_PRINTER_IDLE` | Printer is idle
`IPP_PRINTER_PROCESSING` | Printer is working
`IPP_PRINTER_STOPPED` | Printer is stopped

### ipp_quality_e

#### Description

#### Values

Name | Description
--- | ---
`IPP_QUALITY_DRAFT` | Draft quality
`IPP_QUALITY_HIGH` | High quality
`IPP_QUALITY_NORMAL` | Normal quality

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

#### Description

#### Values

Name | Description
--- | ---
`IPP_ATTRIBUTE` | One or more attributes need to be sent/received
`IPP_DATA` | IPP request data needs to be sent/received
`IPP_ERROR` | An error occurred
`IPP_HEADER` | The request header needs to be sent/received
`IPP_IDLE` | Nothing is happening/request completed

### ipp_status_e

#### Description

IPP status codes...

#### Values

Name | Description
--- | ---
`CUPS_SEE_OTHER` | cups-see-other
`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_CANCELED` | 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()`
- `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

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

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

Name | Description
--- | ---
`http` | HTTP connection to server
`request` | IPP request
`resource` | HTTP resource for POST
`infile` | File to read from or -1 for none
`outfile` | File to write to or -1 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.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

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

#### Returns

Authorization string

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

Name | Description
--- | ---
`http` | HTTP connection
`scheme` | Auth scheme (NULL to clear it)
`data` | Auth data (NULL for none)

#### Returns

Nothing.

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

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