| Headers | cups/cups.h cups/http.h cups/ipp.h |
|---|---|
| Library | -lcups |
| See Also | Programming: Introduction to CUPS Programming Programming: CUPS API References: CUPS Implementation of IPP |
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.
The HTTP APIs use an opaque structure called
http_t to manage connections to
a particular HTTP or IPP server. The
httpConnectEncrypt function is
used to create an instance of this structure for a particular server.
The constant CUPS_HTTP_DEFAULT can be used with all of the
cups functions to refer to the default CUPS server - the functions
create a per-thread http_t as needed.
The IPP APIs use two opaque structures for requests (messages sent to the CUPS scheduler) and responses (messages sent back to your application from the scheduler). The ipp_t type holds a complete request or response and is allocated using the ippNew or ippNewRequest functions and freed using the ippDelete function.
The second opaque structure is called ipp_attribute_t and holds a single IPP attribute which consists of a group tag (ippGetGroupTag), a value type tag (ippGetValueTag), the attribute name (ippGetName), and 1 or more values (ippGetCount, ippGetBoolean, ippGetCollection, ippGetDate, ippGetInteger, ippGetRange, ippGetResolution, and ippGetString). Attributes are added to an ipp_t pointer using one of the ippAdd functions. For example, use ippAddString to add the "printer-uri" and "requesting-user-name" string attributes to a request:
ipp_t *request = ippNewRequest(IPP_GET_JOBS); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://localhost/printers/"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser());
Once you have created an IPP request, use the cups functions to send the request to and read the response from the server. For example, the cupsDoRequest function can be used for simple query operations that do not involve files:
#include <cups/cups.h> ipp_t *get_jobs(void) { ipp_t *request = ippNewRequest(IPP_GET_JOBS); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://localhost/printers/"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser()); return (cupsDoRequest(CUPS_HTTP_DEFAULT, request, "/")); }
The cupsDoRequest function frees the request and returns an IPP response or NULL pointer if the request could not be sent to the server. Once you have a response from the server, you can either use the ippFindAttribute and ippFindNextAttribute functions to find specific attributes, for example:
ipp_t *response; ipp_attribute_t *attr; attr = ippFindAttribute(response, "printer-state", IPP_TAG_ENUM);
You can also walk the list of attributes with a simple for loop like this:
ipp_t *response; ipp_attribute_t *attr; for (attr = ippFirstAttribute(response); attr != NULL; attr = ippNextAttribute(response)) if (ippGetName(attr) == NULL) puts("--SEPARATOR--"); else puts(ippGetName(attr));
The for loop approach is normally used when collecting attributes for multiple objects (jobs, printers, etc.) in a response. Attributes with NULL names indicate a separator between the attributes of each object. For example, the following code will list the jobs returned from our previous get_jobs example code:
ipp_t *response = get_jobs(); if (response != NULL) { ipp_attribute_t *attr; const char *attrname; int job_id = 0; const char *job_name = NULL; const char *job_originating_user_name = NULL; puts("Job ID Owner Title"); puts("------ ---------------- ---------------------------------"); for (attr = ippFirstAttribute(response); attr != NULL; attr = ippNextAttribute(response)) { /* Attributes without names are separators between jobs */ attrname = ippGetName(attr); if (attrname == NULL) { if (job_id > 0) { if (job_name == NULL) job_name = "(withheld)"; if (job_originating_user_name == NULL) job_originating_user_name = "(withheld)"; printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); } job_id = 0; job_name = NULL; job_originating_user_name = NULL; continue; } else if (!strcmp(attrname, "job-id") && ippGetValueTag(attr) == IPP_TAG_INTEGER) job_id = ippGetInteger(attr, 0); else if (!strcmp(attrname, "job-name") && ippGetValueTag(attr) == IPP_TAG_NAME) job_name = ippGetString(attr, 0, NULL); else if (!strcmp(attrname, "job-originating-user-name") && ippGetValueTag(attr) == IPP_TAG_NAME) job_originating_user_name = ippGetString(attr, 0, NULL); } if (job_id > 0) { if (job_name == NULL) job_name = "(withheld)"; if (job_originating_user_name == NULL) job_originating_user_name = "(withheld)"; printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); } }
To ensure proper encoding, the
httpAssembleURIf function must be
used to format a "printer-uri" string for all printer-based requests:
const char *name = "Foo"; char uri[1024]; ipp_t *request; httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), ippPort(), "/printers/%s", name); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
The cupsDoFileRequest and
cupsDoIORequest functions are
used for requests involving files. The
cupsDoFileRequest function
attaches the named file to a request and is typically used when sending a print
file or changing a printer's PPD file:
const char *filename = "/usr/share/cups/data/testprint.ps"; const char *name = "Foo"; char uri[1024]; char resource[1024]; ipp_t *request = ippNewRequest(IPP_PRINT_JOB); ipp_t *response; /* Use httpAssembleURIf for the printer-uri string */ httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), ippPort(), "/printers/%s", name); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser()); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "testprint.ps"); /* Use snprintf for the resource path */ snprintf(resource, sizeof(resource), "/printers/%s", name); response = cupsDoFileRequest(CUPS_HTTP_DEFAULT, request, resource, filename);
The cupsDoIORequest function
optionally attaches a file to the request and optionally saves a file in the
response from the server. It is used when using a pipe for the request
attachment or when using a request that returns a file, currently only
CUPS_GET_DOCUMENT and CUPS_GET_PPD. For example,
the following code will download the PPD file for the sample HP LaserJet
printer driver:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); response = cupsDoIORequest(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd);
The example passes -1 for the input file descriptor to specify
that no file is to be attached to the request. The PPD file attached to the
response is written to the temporary file descriptor we created using the
cupsTempFd function.
The cupsSendRequest and
cupsGetResponse support
asynchronous communications with the server. Unlike the other request
functions, the IPP request is not automatically freed, so remember to
free your request with the ippDelete
function.
File data is attached to the request using the
cupsWriteRequestData
function, while file data returned from the server is read using the
cupsReadResponseData
function. We can rewrite the previous CUPS_GET_PPD example
to use the asynchronous functions quite easily:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); if (cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE) { response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/"); if (response != NULL) { ssize_t bytes; char buffer[8192]; while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) write(tempfd, buffer, bytes); } } /* Free the request! */ ippDelete(request);
The cupsSendRequest function
returns the initial HTTP request status, typically either
HTTP_CONTINUE or HTTP_UNAUTHORIZED. The latter status
is returned when the request requires authentication of some sort. The
cupsDoAuthentication function
must be called when your see HTTP_UNAUTHORIZED and the request
re-sent. We can add authentication support to our example code by using a
do ... while loop:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; http_status_t status; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); /* Loop for authentication */ do { status = cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/"); if (status == HTTP_UNAUTHORIZED) { /* Try to authenticate, break out of the loop if that fails */ if (cupsDoAuthentication(CUPS_HTTP_DEFAULT, "POST", "/")) break; } } while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED); if (status == HTTP_CONTINUE) { response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/"); if (response != NULL) { ssize_t bytes; char buffer[8192]; while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) write(tempfd, buffer, bytes); } } /* Free the request! */ ippDelete(request);
Authenticate a request.
int cupsDoAuthentication (
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT0 on success, -1 on error
This function should be called in response to a HTTP_STATUS_UNAUTHORIZED
status, prior to resubmitting your request.
Do an IPP request with a file.
ipp_t *cupsDoFileRequest (
http_t *http,
ipp_t *request,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULTNULL for noneResponse data
This function sends the IPP request and attached file to the specified
server, retrying and authenticating as necessary. The request is freed with
ippDelete.
Do an IPP request with file descriptors.
ipp_t *cupsDoIORequest (
http_t *http,
ipp_t *request,
const char *resource,
int infile,
int outfile
);
CUPS_HTTP_DEFAULTResponse data
This function sends the IPP request with the optional input file "infile" to
the specified server, retrying and authenticating as necessary. The request
is freed with ippDelete.
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.
Do an IPP request.
ipp_t *cupsDoRequest (
http_t *http,
ipp_t *request,
const char *resource
);
CUPS_HTTP_DEFAULTResponse data
This function sends the IPP request to the specified server, retrying
and authenticating as necessary. The request is freed with ippDelete.
Encode printer options into IPP attributes.
void cupsEncodeOptions (
ipp_t *ipp,
int num_options,
cups_option_t *options
);
This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.
Encode printer options into IPP attributes for a group.
void cupsEncodeOptions2 (
ipp_t *ipp,
int num_options,
cups_option_t *options,
ipp_tag_t group_tag
);
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.
Get available printer devices.
ipp_status_t cupsGetDevices (
http_t *http,
int timeout,
const char *include_schemes,
const char *exclude_schemes,
cups_device_cb_t callback,
void *user_data
);
CUPS_HTTP_DEFAULTCUPS_TIMEOUT_DEFAULTCUPS_INCLUDE_ALLCUPS_EXCLUDE_NONERequest status - IPP_OK on success.
This function sends a CUPS-Get-Devices request and streams the discovered devices to the specified callback function. The "timeout" parameter controls how long the request lasts, while the "include_schemes" and "exclude_schemes" parameters provide comma-delimited lists of backends to include or omit from the request respectively.
Get a file from the server.
http_status_t cupsGetFd (
http_t *http,
const char *resource,
int fd
);
CUPS_HTTP_DEFAULTHTTP status
This function returns HTTP_STATUS_OK when the file is successfully retrieved.
Get a file from the server.
http_status_t cupsGetFile (
http_t *http,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULTHTTP status
This function returns HTTP_STATUS_OK when the file is successfully retrieved.
Get a response to an IPP request.
ipp_t *cupsGetResponse (
http_t *http,
const char *resource
);
CUPS_HTTP_DEFAULTResponse or NULL on HTTP error
Use this function to get the response for an IPP request sent using
cupsSendRequest. For requests that return additional data, use
cupsReadResponseData after getting a successful response,
otherwise call httpFlush to complete the response processing.
Return the last IPP status code received on the current thread.
ipp_status_t cupsLastError (void);
IPP status code from last request
Return the last IPP status-message received on the current thread.
const char *cupsLastErrorString (void);
status-message text from last request
Put a file on the server.
http_status_t cupsPutFd (
http_t *http,
const char *resource,
int fd
);
CUPS_HTTP_DEFAULTHTTP status
This function returns HTTP_STATUS_CREATED when the file is stored
successfully.
Put a file on the server.
http_status_t cupsPutFile (
http_t *http,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULTHTTP status
This function returns HTTP_CREATED when the file is stored
successfully.
Read additional data after the IPP response.
ssize_t cupsReadResponseData (
http_t *http,
char *buffer,
size_t length
);
CUPS_HTTP_DEFAULTBytes read, 0 on EOF, -1 on error
This function is used after cupsGetResponse to read the PPD or document
files from CUPS_GET_PPD and CUPS_GET_DOCUMENT requests,
respectively.
Send an IPP request.
http_status_t cupsSendRequest (
http_t *http,
ipp_t *request,
const char *resource,
size_t length
);
CUPS_HTTP_DEFAULTCUPS_LENGTH_VARIABLEInitial HTTP status
Use cupsWriteRequestData to write any additional data (document, PPD
file, etc.) for the request, cupsGetResponse to get the IPP response,
and cupsReadResponseData to read any additional data following the
response. Only one request can be sent/queued at a time per http_t
connection.
Returns the initial HTTP status code, which will be HTTP_STATUS_CONTINUE
on a successful send of the request.
Note: Unlike cupsDoFileRequest, cupsDoIORequest, and
cupsDoRequest, the request is NOT freed with ippDelete.
Write additional data after an IPP request.
http_status_t cupsWriteRequestData (
http_t *http,
const char *buffer,
size_t length
);
CUPS_HTTP_DEFAULTHTTP_STATUS_CONTINUE if OK or HTTP status on error
This function is used after cupsSendRequest to provide a PPD and
after cupsStartDocument to provide a document file.
Accept a new HTTP client connection from the specified listening socket.
http_t *httpAcceptConnection (
int fd,
int blocking
);
HTTP connection or NULL
Allocates and adds a single credential to an array.
int httpAddCredential (
cups_array_t *credentials,
const void *data,
size_t datalen
);
0 on success, -1 on error
Use cupsArrayNew(NULL, NULL) to create a credentials array.
Check for the "any" address.
int httpAddrAny (
const http_addr_t *addr
);
1 if "any", 0 otherwise
Close a socket created by httpAddrConnect or
httpAddrListen.
int httpAddrClose (
http_addr_t *addr,
int fd
);
NULL0 on success, -1 on failure
Pass NULL for sockets created with httpAddrConnect and the
listen address for sockets created with httpAddrListen. This will
ensure that domain sockets are removed when closed.
Compare two addresses.
int httpAddrEqual (
const http_addr_t *addr1,
const http_addr_t *addr2
);
1 if equal, 0 if not
Get the address family of an address.
int httpAddrFamily (
http_addr_t *addr
);
Address family
Return the length of the address in bytes.
int httpAddrLength (
const http_addr_t *addr
);
Length in bytes
Create a listening socket bound to the specified address and port.
int httpAddrListen (
http_addr_t *addr,
int port
);
Socket or -1 on error
Check for the local loopback address.
int httpAddrLocalhost (
const http_addr_t *addr
);
1 if local host, 0 otherwise
Lookup the hostname associated with the address.
char *httpAddrLookup (
const http_addr_t *addr,
char *name,
int namelen
);
Host name
Get the port number associated with an address.
int httpAddrPort (
http_addr_t *addr
);
Port number
Convert an address to a numeric string.
char *httpAddrString (
const http_addr_t *addr,
char *s,
int slen
);
Numeric address string
Assemble a uniform resource identifier from its components.
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
);
URI status
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.
Assemble a uniform resource identifier from its components with a formatted resource.
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,
...
);
URI status
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.
Assemble a name-based UUID URN conforming to RFC 4122.
char *httpAssembleUUID (
const char *server,
int port,
const char *name,
int number,
char *buffer,
size_t bufsize
);
UUID string
This function creates a unique 128-bit identifying number using the server
name, port number, random data, and optionally an object name and/or object
number. The result is formatted as a UUID URN as defined in RFC 4122.
The buffer needs to be at least 46 bytes in size.
Set blocking/non-blocking behavior on a connection.
void httpBlocking (
http_t *http,
int b
);
Check to see if there is a pending response from the server.
int httpCheck (
http_t *http
);
0 = no data, 1 = data available
Clear the cookie value(s).
void httpClearCookie (
http_t *http
);
Clear HTTP request fields.
void httpClearFields (
http_t *http
);
Close an HTTP connection.
void httpClose (
http_t *http
);
Compare two sets of X.509 credentials.
int httpCompareCredentials (
cups_array_t *cred1,
cups_array_t *cred2
);
1 if they match, 0 if they do not
Connect to a HTTP server.
http_t *httpConnect (
const char *host,
int port
);
New HTTP connection
This function is deprecated - use httpConnect2 instead.
Connect to a HTTP server.
http_t *httpConnect2 (
const char *host,
int port,
http_addrlist_t *addrlist,
int family,
http_encryption_t encryption,
int blocking,
int msec,
int *cancel
);
AF_UNSPEC for anyNew HTTP connection
Connect to a HTTP server using encryption.
http_t *httpConnectEncrypt (
const char *host,
int port,
http_encryption_t encryption
);
New HTTP connection
This function is now deprecated. Please use the httpConnect2 function
instead.
Base64-decode a string.
char *httpDecode64 (
char *out,
const char *in
);
Decoded string
This function is deprecated. Use the httpDecode64_2() function instead which provides buffer length arguments.
Base64-decode a string.
char *httpDecode64_2 (
char *out,
int *outlen,
const char *in
);
Decoded string
Send a DELETE request to the server.
int httpDelete (
http_t *http,
const char *uri
);
Status of call (0 = success)
Base64-encode a string.
char *httpEncode64 (
char *out,
const char *in
);
Encoded string
This function is deprecated. Use the httpEncode64_2() function instead which provides buffer length arguments.
Base64-encode a string.
char *httpEncode64_2 (
char *out,
int outlen,
const char *in,
int inlen
);
Encoded string
Set the required encryption on the link.
int httpEncryption (
http_t *http,
http_encryption_t e
);
-1 on error, 0 on success
Get the last error on a connection.
int httpError (
http_t *http
);
Error code (errno) value
Return the HTTP field enumeration value for a field name.
http_field_t httpFieldValue (
const char *name
);
Field index
Flush data from a HTTP connection.
void httpFlush (
http_t *http
);
Flush data in write buffer.
int httpFlushWrite (
http_t *http
);
Bytes written or -1 on error
Free an array of credentials.
void httpFreeCredentials (
cups_array_t *credentials
);
Send a GET request to the server.
int httpGet (
http_t *http,
const char *uri
);
Status of call (0 = success)
Get the most recent activity for a connection.
time_t httpGetActivity (
http_t *http
);
Time of last read or write
The return value is the UNIX time of the last read or write.
Get the address of the connected peer of a connection.
http_addr_t *httpGetAddress (
http_t *http
);
Connected address or NULL
Returns NULL if the socket is currently unconnected.
Get the current authorization string.
char *httpGetAuthString (
http_t *http
);
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.
Get the blocking/non-block state of a connection.
int httpGetBlocking (
http_t *http
);
1 if blocking, 0 if non-blocking
Get a common content encoding, if any, between the client and server.
const char *httpGetContentEncoding (
http_t *http
);
Content-Coding value or
NULL for the identity
coding.
This function uses the value of the Accepts-Encoding HTTP header and must be called after receiving a response from the server or a request from the client. The value returned can be use in subsequent requests (for clients) or in the response (for servers) in order to compress the content stream.
Get any cookie data from the response.
const char *httpGetCookie (
http_t *http
);
Cookie data or NULL
Get a formatted date/time string from a time value.
const char *httpGetDateString (
time_t t
);
Date/time string
Get a formatted date/time string from a time value.
const char *httpGetDateString2 (
time_t t,
char *s,
int slen
);
Date/time string
Get a time value from a formatted date/time string.
time_t httpGetDateTime (
const char *s
);
UNIX time
Get the current encryption mode of a connection.
http_encryption_t httpGetEncryption (
http_t *http
);
Current encryption mode
This function returns the encryption mode for the connection. Use the
httpIsEncrypted function to determine whether a TLS session has
been established.
Get the value of the Expect header, if any.
http_status_t httpGetExpect (
http_t *http
);
Expect: status, if any
Returns HTTP_STATUS_NONE if there is no Expect header, otherwise
returns the expected HTTP status code, typically HTTP_STATUS_CONTINUE.
Get the file descriptor associated with a connection.
int httpGetFd (
http_t *http
);
File descriptor or -1 if none
Get a field value from a request/response.
const char *httpGetField (
http_t *http,
http_field_t field
);
Field value
Lookup a hostname or IPv4 address, and return address records for the specified name.
struct hostent *httpGetHostByName (
const char *name
);
Host entry
Get the FQDN for the connection or local system.
const char *httpGetHostname (
http_t *http,
char *s,
int slen
);
FQDN for connection or system
When "http" points to a connected socket, return the hostname or address that was used in the call to httpConnect() or httpConnectEncrypt(), or the address of the client for the connection from httpAcceptConnection(). Otherwise, return the FQDN for the local system using both gethostname() and gethostbyname() to get the local hostname with domain.
Get the current Keep-Alive state of the connection.
http_keepalive_t httpGetKeepAlive (
http_t *http
);
Keep-Alive state
Get the amount of data remaining from the content-length or transfer-encoding fields.
int httpGetLength (
http_t *http
);
Content length
This function is deprecated and will not return lengths larger than 2^31 - 1; use httpGetLength2() instead.
Get the amount of data remaining from the content-length or transfer-encoding fields.
off_t httpGetLength2 (
http_t *http
);
Content length
This function returns the complete content length, even for content larger than 2^31 - 1.
Get the number of bytes that are buffered for writing.
size_t httpGetPending (
http_t *http
);
Number of bytes buffered
Get the number of bytes that can be read without blocking.
size_t httpGetReady (
http_t *http
);
Number of bytes available
Get the number of remaining bytes in the message body or current chunk.
size_t httpGetRemaining (
http_t *http
);
Remaining bytes
The httpIsChunked function can be used to determine whether the
message body is chunked or fixed-length.
Get the current state of the HTTP request.
http_state_t httpGetState (
http_t *http
);
HTTP state
Get the status of the last HTTP request.
http_status_t httpGetStatus (
http_t *http
);
HTTP status
Get a sub-field value.
char *httpGetSubField (
http_t *http,
http_field_t field,
const char *name,
char *value
);
Value or NULL
Get a sub-field value.
char *httpGetSubField2 (
http_t *http,
http_field_t field,
const char *name,
char *value,
int valuelen
);
Value or NULL
Get the HTTP version at the other end.
http_version_t httpGetVersion (
http_t *http
);
Version number
Get a line of text from a HTTP connection.
char *httpGets (
char *line,
int length,
http_t *http
);
Line or NULL
Send a HEAD request to the server.
int httpHead (
http_t *http,
const char *uri
);
Status of call (0 = success)
Initialize the HTTP interface library and set the default HTTP proxy (if any).
void httpInitialize (void);
Report whether a message body is chunked.
int httpIsChunked (
http_t *http
);
1 if chunked, 0 if not
This function returns non-zero if the message body is composed of variable-length chunks.
Report whether a connection is encrypted.
int httpIsEncrypted (
http_t *http
);
1 if encrypted, 0 if not
This function returns non-zero if the connection is currently encrypted.
Compute the MD5 sum of the username:group:password.
char *httpMD5 (
const char *username,
const char *realm,
const char *passwd,
char md5[33]
);
MD5 sum
Combine the MD5 sum of the username, group, and password with the server-supplied nonce value, method, and request-uri.
char *httpMD5Final (
const char *nonce,
const char *method,
const char *resource,
char md5[33]
);
New sum
Convert an MD5 sum to a character string.
char *httpMD5String (
const unsigned char *sum,
char md5[33]
);
MD5 sum in hex
Send an OPTIONS request to the server.
int httpOptions (
http_t *http,
const char *uri
);
Status of call (0 = success)
Peek at data from a HTTP connection.
ssize_t httpPeek (
http_t *http,
char *buffer,
size_t length
);
Number of bytes copied
This function copies available data from the given HTTP connection, reading
a buffer as needed. The data is still available for reading using
httpRead or httpRead2.
For non-blocking connections the usual timeouts apply.
Send a POST request to the server.
int httpPost (
http_t *http,
const char *uri
);
Status of call (0 = success)
Send a PUT request to the server.
int httpPut (
http_t *http,
const char *uri
);
Status of call (0 = success)
Read data from a HTTP connection.
int httpRead (
http_t *http,
char *buffer,
int length
);
Number of bytes read
This function is deprecated. Use the httpRead2() function which can read more than 2GB of data.
Read data from a HTTP connection.
ssize_t httpRead2 (
http_t *http,
char *buffer,
size_t length
);
Number of bytes read
Read a HTTP request from a connection.
http_state_t httpReadRequest (
http_t *http,
char *uri,
size_t urilen
);
New state of connection
Reconnect to a HTTP server.
int httpReconnect (
http_t *http
);
0 on success, non-zero on failure
This function is deprecated. Please use the httpReconnect2 function
instead.
Reconnect to a HTTP server with timeout and optional cancel.
int httpReconnect2 (
http_t *http,
int msec,
int *cancel
);
0 on success, non-zero on failure
Resolve the hostname of the HTTP connection address.
const char *httpResolveHostname (
http_t *http,
char *buffer,
size_t bufsize
);
Resolved hostname or NULL
Separate a Universal Resource Identifier into its components.
void httpSeparate (
const char *uri,
char *scheme,
char *username,
char *host,
int *port,
char *resource
);
This function is deprecated; use the httpSeparateURI() function instead.
Separate a Universal Resource Identifier into its components.
void httpSeparate2 (
const char *uri,
char *scheme,
int schemelen,
char *username,
int usernamelen,
char *host,
int hostlen,
int *port,
char *resource,
int resourcelen
);
This function is deprecated; use the httpSeparateURI() function instead.
Separate a Universal Resource Identifier into its components.
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
);
Result of separation
Set the current authorization string.
void httpSetAuthString (
http_t *http,
const char *scheme,
const char *data
);
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().
Set the cookie value(s).
void httpSetCookie (
http_t *http,
const char *cookie
);
Set the credentials associated with an encrypted connection.
int httpSetCredentials (
http_t *http,
cups_array_t *credentials
);
Status of call (0 = success)
Set the default value of an HTTP header.
void httpSetDefaultField (
http_t *http,
http_field_t field,
const char *value
);
Currently only HTTP_FIELD_ACCEPT_ENCODING, HTTP_FIELD_SERVER,
and HTTP_FIELD_USER_AGENT can be set.
Set the Expect: header in a request.
void httpSetExpect (
http_t *http,
http_status_t expect
);
HTTP_STATUS_CONTINUE)Currently only HTTP_STATUS_CONTINUE is supported for the "expect"
argument.
Set the value of an HTTP header.
void httpSetField (
http_t *http,
http_field_t field,
const char *value
);
Set the current Keep-Alive state of a connection.
void httpSetKeepAlive (
http_t *http,
http_keepalive_t keep_alive
);
Set the content-length and content-encoding.
void httpSetLength (
http_t *http,
size_t length
);
Set read/write timeouts and an optional callback.
void httpSetTimeout (
http_t *http,
double timeout,
http_timeout_cb_t cb,
void *user_data
);
The optional timeout callback receives both the HTTP connection and a user data pointer and must return 1 to continue or 0 to error (time) out.
Shutdown one side of an HTTP connection.
void httpShutdown (
http_t *http
);
Return the string describing a HTTP state value.
const char *httpStateString (
http_state_t state
);
State string
Return a short string describing a HTTP status code.
const char *httpStatus (
http_status_t status
);
Localized status string
The returned string is localized to the current POSIX locale and is based on the status strings defined in RFC 2616.
Send an TRACE request to the server.
int httpTrace (
http_t *http,
const char *uri
);
Status of call (0 = success)
Return a string describing a URI status code.
const char *httpURIStatusString (
http_uri_status_t status
);
Localized status string
Update the current HTTP state for incoming data.
http_status_t httpUpdate (
http_t *http
);
HTTP status
Wait for data available on a connection.
int httpWait (
http_t *http,
int msec
);
1 if data is available, 0 otherwise
Write data to a HTTP connection.
int httpWrite (
http_t *http,
const char *buffer,
int length
);
Number of bytes written
This function is deprecated. Use the httpWrite2() function which can write more than 2GB of data.
Write data to a HTTP connection.
ssize_t httpWrite2 (
http_t *http,
const char *buffer,
size_t length
);
Number of bytes written
Write a HTTP response to a client connection.
int httpWriteResponse (
http_t *http,
http_status_t status
);
0 on success, -1 on error
Add a boolean attribute to an IPP message.
ipp_attribute_t *ippAddBoolean (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
char value
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an array of boolean values.
ipp_attribute_t *ippAddBooleans (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const char *values
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a collection value.
ipp_attribute_t *ippAddCollection (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_t *value
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an array of collection values.
ipp_attribute_t *ippAddCollections (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const ipp_t **values
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a date attribute to an IPP message.
ipp_attribute_t *ippAddDate (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
const ipp_uchar_t *value
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a integer attribute to an IPP message.
ipp_attribute_t *ippAddInteger (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int value
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported values include enum (IPP_TAG_ENUM) and integer
(IPP_TAG_INTEGER).
Add an array of integer values.
ipp_attribute_t *ippAddIntegers (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const int *values
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported values include enum (IPP_TAG_ENUM) and integer
(IPP_TAG_INTEGER).
Add an octetString value to an IPP message.
ipp_attribute_t *ippAddOctetString (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
const void *data,
int datalen
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an out-of-band value to an IPP message.
ipp_attribute_t *ippAddOutOfBand (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported out-of-band values include unsupported-value
(IPP_TAG_UNSUPPORTED_VALUE), default (IPP_TAG_DEFAULT), unknown
(IPP_TAG_UNKNOWN), no-value (IPP_TAG_NOVALUE), not-settable
(IPP_TAG_NOTSETTABLE), delete-attribute (IPP_TAG_DELETEATTR), and
admin-define (IPP_TAG_ADMINDEFINE).
Add a range of values to an IPP message.
ipp_attribute_t *ippAddRange (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int lower,
int upper
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
The lower parameter must be less than or equal to the upper parameter.
Add ranges of values to an IPP message.
ipp_attribute_t *ippAddRanges (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const int *lower,
const int *upper
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a resolution value to an IPP message.
ipp_attribute_t *ippAddResolution (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_res_t units,
int xres,
int yres
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add resolution values to an IPP message.
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
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a group separator to an IPP message.
ipp_attribute_t *ippAddSeparator (
ipp_t *ipp
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
Add a language-encoded string to an IPP message.
ipp_attribute_t *ippAddString (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *value
);
New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported string values include charset (IPP_TAG_CHARSET), keyword
(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
(IPP_TAG_NAMELANG), text (code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), and uriScheme
(IPP_TAG_URISCHEME).
The language parameter must be non-NULL for nameWithLanguage and
textWithLanguage string values and must be NULL for all other string values.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringf (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
...
);
NULL for default)New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document
(IPP_TAG_DOCUMENT), event notification
(IPP_TAG_EVENT_NOTIFICATION), operation (IPP_TAG_OPERATION),
printer (IPP_TAG_PRINTER), subscription (IPP_TAG_SUBSCRIPTION),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported string values include charset (IPP_TAG_CHARSET), keyword
(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
(IPP_TAG_NAMELANG), text (code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), and uriScheme
(IPP_TAG_URISCHEME).
The language parameter must be non-NULL for nameWithLanguage
and textWithLanguage string values and must be NULL for all other
string values.
The format parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringfv (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
va_list ap
);
NULL for default)New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document
(IPP_TAG_DOCUMENT), event notification
(IPP_TAG_EVENT_NOTIFICATION), operation (IPP_TAG_OPERATION),
printer (IPP_TAG_PRINTER), subscription (IPP_TAG_SUBSCRIPTION),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported string values include charset (IPP_TAG_CHARSET), keyword
(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
(IPP_TAG_NAMELANG), text (code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), and uriScheme
(IPP_TAG_URISCHEME).
The language parameter must be non-NULL for nameWithLanguage
and textWithLanguage string values and must be NULL for all other
string values.
The format parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments are passed in the
stdarg pointer ap. The formatted string is truncated as needed to the
maximum length of the corresponding value type.
Add language-encoded strings to an IPP message.
ipp_attribute_t *ippAddStrings (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const char *language,
const char *const *values
);
NULL for default)New attribute
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Supported string values include charset (IPP_TAG_CHARSET), keyword
(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
(IPP_TAG_NAMELANG), text (code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), and uriScheme
(IPP_TAG_URISCHEME).
The language parameter must be non-NULL for nameWithLanguage and
textWithLanguage string values and must be NULL for all other string values.
Convert the attribute's value to a string.
size_t ippAttributeString (
ipp_attribute_t *attr,
char *buffer,
size_t bufsize
);
Number of bytes less nul
Returns the number of bytes that would be written, not including the trailing nul. The buffer pointer can be NULL to get the required length, just like (v)snprintf.
Determine whether an attribute contains the specified value or is within the list of ranges.
int ippContainsInteger (
ipp_attribute_t *attr,
int value
);
1 on a match, 0 on no match
Returns non-zero when the attribute contains either a matching integer or enum value, or the value falls within one of the rangeOfInteger values for the attribute.
Determine whether an attribute contains the specified string value.
int ippContainsString (
ipp_attribute_t *attr,
const char *value
);
1 on a match, 0 on no match
Returns non-zero when the attribute contains a matching charset, keyword, language, mimeMediaType, name, text, URI, or URI scheme value.
Copy an attribute.
ipp_attribute_t *ippCopyAttribute (
ipp_t *dst,
ipp_attribute_t *srcattr,
int quickcopy
);
New attribute
The specified attribute, attr, is copied to the destination IPP message.
When quickcopy is non-zero, a "shallow" reference copy of the attribute is
created - this should only be done as long as the original source IPP message will
not be freed for the life of the destination.
Copy attributes from one IPP message to another.
int ippCopyAttributes (
ipp_t *dst,
ipp_t *src,
int quickcopy,
ipp_copycb_t cb,
void *context
);
NULL for none1 on success, 0 on error
Zero or more attributes are copied from the source IPP message, src, to the
destination IPP message, dst. When quickcopy is non-zero, a "shallow"
reference copy of the attribute is created - this should only be done as long as the
original source IPP message will not be freed for the life of the destination.
The cb and context parameters provide a generic way to "filter" the
attributes that are copied - the function must return 1 to copy the attribute or
0 to skip it. The function may also choose to do a partial copy of the source attribute
itself.
Create a CUPS array of attribute names from the given requested-attributes attribute.
cups_array_t *ippCreateRequestedArray (
ipp_t *request
);
CUPS array or NULL if all
This function creates a (sorted) CUPS array of attribute names matching the
list of "requested-attribute" values supplied in an IPP request. All IANA-
registered values are supported in addition to the CUPS IPP extension
attributes.
The request parameter specifies the request message that was read from
the client.
NULL is returned if all attributes should be returned. Otherwise, the
result is a sorted array of attribute names, where cupsArrayFind(array,
"attribute-name") will return a non-NULL pointer. The array must be freed
using the cupsArrayDelete function.
Convert from RFC 1903 Date/Time format to UNIX time in seconds.
time_t ippDateToTime (
const ipp_uchar_t *date
);
UNIX time value
Delete an IPP message.
void ippDelete (
ipp_t *ipp
);
Delete a single attribute in an IPP message.
void ippDeleteAttribute (
ipp_t *ipp,
ipp_attribute_t *attr
);
Delete values in an attribute.
int ippDeleteValues (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int count
);
1 on success, 0 on failure
The element parameter specifies the first value to delete, starting at
0. It must be less than the number of values returned by ippGetCount.
The attr parameter may be modified as a result of setting the value.
Deleting all values in an attribute deletes the attribute.
Return a string corresponding to the enum value.
const char *ippEnumString (
const char *attrname,
int enumvalue
);
Enum string
Return the value associated with a given enum string.
int ippEnumValue (
const char *attrname,
const char *enumstring
);
Enum value or -1 if unknown
Return a name for the given status code.
const char *ippErrorString (
ipp_status_t error
);
Text string
Return a status code for the given name.
ipp_status_t ippErrorValue (
const char *name
);
IPP status code
Find a named attribute in a request.
ipp_attribute_t *ippFindAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
Starting with CUPS 2.0, the attribute name can contain a hierarchical list of attribute and member names separated by slashes, for example "media-col/media-size".
Find the next named attribute in a request.
ipp_attribute_t *ippFindNextAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
Starting with CUPS 2.0, the attribute name can contain a hierarchical list of attribute and member names separated by slashes, for example "media-col/media-size".
Return the first attribute in the message.
ipp_attribute_t *ippFirstAttribute (
ipp_t *ipp
);
First attribute or NULL if none
Get a boolean value for an attribute.
int ippGetBoolean (
ipp_attribute_t *attr,
int element
);
Boolean value or 0 on error
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get a collection value for an attribute.
ipp_t *ippGetCollection (
ipp_attribute_t *attr,
int element
);
Collection value or NULL on error
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the number of values in an attribute.
int ippGetCount (
ipp_attribute_t *attr
);
Number of values or 0 on error
Get a date value for an attribute.
const ipp_uchar_t *ippGetDate (
ipp_attribute_t *attr,
int element
);
Date value or NULL
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the group associated with an attribute.
ipp_tag_t ippGetGroupTag (
ipp_attribute_t *attr
);
Group tag or IPP_TAG_ZERO on error
Get the integer/enum value for an attribute.
int ippGetInteger (
ipp_attribute_t *attr,
int element
);
Value or 0 on error
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the attribute name.
const char *ippGetName (
ipp_attribute_t *attr
);
Attribute name or NULL for separators
Get an octetString value from an IPP attribute.
void *ippGetOctetString (
ipp_attribute_t *attr,
int element,
int *datalen
);
Pointer to octetString data
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the operation ID in an IPP message.
ipp_op_t ippGetOperation (
ipp_t *ipp
);
Operation ID or 0 on error
Get a rangeOfInteger value from an attribute.
int ippGetRange (
ipp_attribute_t *attr,
int element,
int *uppervalue
);
Lower value of range or 0
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the request ID from an IPP message.
int ippGetRequestId (
ipp_t *ipp
);
Request ID or 0 on error
Get a resolution value for an attribute.
int ippGetResolution (
ipp_attribute_t *attr,
int element,
int *yres,
ipp_res_t *units
);
Horizontal/cross feed resolution or 0
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the IPP message state.
ipp_state_t ippGetState (
ipp_t *ipp
);
IPP message state value
Get the status code from an IPP response or event message.
ipp_status_t ippGetStatusCode (
ipp_t *ipp
);
Status code in IPP message
Return the value...
const char *ippGetString (
ipp_attribute_t *attr,
int element,
const char **language
);
NULL for don't care)Get the string and optionally the language code for an attribute.
The element parameter specifies which value to get from 0 to
ippGetCount(attr) - 1.
Get the value tag for an attribute.
ipp_tag_t ippGetValueTag (
ipp_attribute_t *attr
);
Value tag or IPP_TAG_ZERO on error
Get the major and minor version number from an IPP message.
int ippGetVersion (
ipp_t *ipp,
int *minor
);
NULLMajor version number or 0 on error
Compute the length of an IPP message.
size_t ippLength (
ipp_t *ipp
);
Size of IPP message
Allocate a new IPP message.
ipp_t *ippNew (void);
New IPP message
Allocate a new IPP request message.
ipp_t *ippNewRequest (
ipp_op_t op
);
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.
Allocate a new IPP response message.
ipp_t *ippNewResponse (
ipp_t *request
);
IPP response message
The new response message is initialized with the same version-number, request-id, attributes-charset, and attributes-natural-language as the provided request message. If the attributes-charset or attributes-natural-language attributes are missing from the request, "utf-8" and a value derived from the current locale are substituted, respectively.
Return the next attribute in the message.
ipp_attribute_t *ippNextAttribute (
ipp_t *ipp
);
Next attribute or NULL if none
Return a name for the given operation id.
const char *ippOpString (
ipp_op_t op
);
Name
Return an operation id for the given name.
ipp_op_t ippOpValue (
const char *name
);
Operation ID
Return the default IPP port number.
int ippPort (void);
Port number
Read data for an IPP message from a HTTP connection.
ipp_state_t ippRead (
http_t *http,
ipp_t *ipp
);
Current state
Read data for an IPP message from a file.
ipp_state_t ippReadFile (
int fd,
ipp_t *ipp
);
Current state
Read data for an IPP message.
ipp_state_t ippReadIO (
void *src,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Set a boolean value in an attribute.
int ippSetBoolean (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int boolvalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set a collection value in an attribute.
int ippSetCollection (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_t *colvalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set a date value in an attribute.
int ippSetDate (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const ipp_uchar_t *datevalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set the group tag of an attribute.
int ippSetGroupTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t group_tag
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The group parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
event notification (IPP_TAG_EVENT_NOTIFICATION), operation
(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Set an integer or enum value in an attribute.
int ippSetInteger (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int intvalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set the name of an attribute.
int ippSetName (
ipp_t *ipp,
ipp_attribute_t **attr,
const char *name
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
Set an octetString value in an IPP attribute.
int ippSetOctetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const void *data,
int datalen
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set the operation ID in an IPP request message.
int ippSetOperation (
ipp_t *ipp,
ipp_op_t op
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
Set the default port number.
void ippSetPort (
int p
);
Set a rangeOfInteger value in an attribute.
int ippSetRange (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int lowervalue,
int uppervalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set the request ID in an IPP message.
int ippSetRequestId (
ipp_t *ipp,
int request_id
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The request_id parameter must be greater than 0.
Set a resolution value in an attribute.
int ippSetResolution (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_res_t unitsvalue,
int xresvalue,
int yresvalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set the current state of the IPP message.
int ippSetState (
ipp_t *ipp,
ipp_state_t state
);
1 on success, 0 on failure
Set the status code in an IPP response or event message.
int ippSetStatusCode (
ipp_t *ipp,
ipp_status_t status
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
Set a string value in an attribute.
int ippSetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *strvalue
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
Set a formatted string value of an attribute.
int ippSetStringf (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
...
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
The format parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Set a formatted string value of an attribute.
int ippSetStringfv (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
va_list ap
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
The element parameter specifies which value to set from 0 to
ippGetCount(attr).
The format parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Set the value tag of an attribute.
int ippSetValueTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t value_tag
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The attr parameter may be modified as a result of setting the value.
Integer (IPP_TAG_INTEGER) values can be promoted to rangeOfInteger
(IPP_TAG_RANGE) values, the various string tags can be promoted to name
(IPP_TAG_NAME) or nameWithLanguage (IPP_TAG_NAMELANG) values, text
(IPP_TAG_TEXT) values can be promoted to textWithLanguage
(IPP_TAG_TEXTLANG) values, and all values can be demoted to the various
out-of-band value tags such as no-value (IPP_TAG_NOVALUE). All other changes
will be rejected.
Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
code in the "attributes-natural-language" attribute or, if not present, the language
code for the current locale.
Set the version number in an IPP message.
int ippSetVersion (
ipp_t *ipp,
int major,
int minor
);
1 on success, 0 on failure
The ipp parameter refers to an IPP message previously created using
the ippNew, ippNewRequest, or ippNewResponse functions.
The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
Return the name corresponding to a state value.
const char *ippStateString (
ipp_state_t state
);
State name
Return the tag name corresponding to a tag value.
const char *ippTagString (
ipp_tag_t tag
);
Tag name
The returned names are defined in RFC 2911 and 3382.
Return the tag value corresponding to a tag name.
ipp_tag_t ippTagValue (
const char *name
);
Tag value
The tag names are defined in RFC 2911 and 3382.
Convert from UNIX time to RFC 1903 format.
const ipp_uchar_t *ippTimeToDate (
time_t t
);
RFC-1903 date/time data
Validate the contents of an attribute.
int ippValidateAttribute (
ipp_attribute_t *attr
);
1 if valid, 0 otherwise
This function validates the contents of an attribute based on the name and value tag. 1 is returned if the attribute is valid, 0 otherwise. On failure, cupsLastErrorString() is set to a human-readable message.
Validate all attributes in an IPP message.
int ippValidateAttributes (
ipp_t *ipp
);
1 if valid, 0 otherwise
This function validates the contents of the IPP message, including each
attribute. Like ippValidateAttribute, cupsLastErrorString() is set
to a human-readable message on failure.
Write data for an IPP message to a HTTP connection.
ipp_state_t ippWrite (
http_t *http,
ipp_t *ipp
);
Current state
Write data for an IPP message to a file.
ipp_state_t ippWriteFile (
int fd,
ipp_t *ipp
);
Current state
Write data for an IPP message.
ipp_state_t ippWriteIO (
void *dst,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Local functions...
typedef struct gss_auth_identity gss_auth_identity_desc;
Socket address union, which makes using IPv6 and other address types easier and more portable.
typedef union _http_addr_u / http_addr_t;
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
typedef struct http_addrlist_s / http_addrlist_t;
HTTP authentication types
typedef enum http_auth_e http_auth_t;
HTTP credential data
typedef struct http_credential_s http_credential_t;
HTTP transfer encoding values
typedef enum http_encoding_e http_encoding_t;
HTTP encryption values
typedef enum http_encryption_e http_encryption_t;
HTTP field names
typedef enum http_field_e http_field_t;
HTTP keep-alive values
typedef enum http_keepalive_e http_keepalive_t;
HTTP state values; states are server-oriented...
typedef enum http_state_e http_state_t;
HTTP connection type
typedef struct _http_s http_t;
HTTP timeout callback
typedef int (*http_timeout_cb_t)(http_t *http, void *user_data);
Level of trust for credentials
typedef enum http_trust_e http_trust_t;
URI en/decode flags
typedef enum http_uri_coding_e http_uri_coding_t;
URI separation status
typedef enum http_uri_status_e http_uri_status_t;
HTTP version numbers
typedef enum http_version_e http_version_t;
IPP attribute
typedef struct _ipp_attribute_s ipp_attribute_t;
The following structures are PRIVATE starting with CUPS 1.6/macOS 10.8. Please use the new accessor functions available in CUPS 1.6 and later, as these definitions will be moved to a private header file in a future release.
typedef int (*ipp_copycb_t)(void *context, ipp_t *dst, ipp_attribute_t *attr);
Document states
typedef enum ipp_dstate_e ipp_dstate_t;
Job collation types
typedef enum ipp_finishings_e ipp_finish_t;
IPP IO Callback Function
typedef ssize_t (*ipp_iocb_t)(void *context, ipp_uchar_t *buffer, size_t bytes);
Job collation types
typedef enum ipp_jcollate_e ipp_jcollate_t;
Orientation values
typedef enum ipp_orient_e ipp_orient_t;
Printer states
typedef enum ipp_pstate_e ipp_pstate_t;
Qualities
typedef enum ipp_quality_e ipp_quality_t;
Resolution units
typedef enum ipp_res_e ipp_res_t;
IPP states
typedef enum ipp_state_e ipp_state_t;
IPP request/response data
typedef struct _ipp_s ipp_t;
Unsigned 8-bit integer/character
typedef unsigned char ipp_uchar_t;
Local functions...
struct gss_auth_identity {
gss_buffer_t *credentialsRef;
uint32_t flags;
char *password;
char *realm;
uint32_t type;
char *username;
};
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
struct http_addrlist_s {
http_addr_t addr;
struct http_addrlist_s *next;
};
HTTP credential data
struct http_credential_s {
void *data;
size_t datalen;
};
User data (unused)
struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {
void) context;
void) timeout;
};
HTTP authentication types
HTTP transfer encoding values
HTTP encryption values
HTTP field names
HTTP keep-alive values
HTTP state values; states are server-oriented...
HTTP status codes
Level of trust for credentials
URI en/decode flags
URI separation status
HTTP version numbers
Document states
Finishings
Job collation types
Job states
IPP operations
ippOpValueOrientation values
Printer states
Qualities
Resolution units
IPP states
IPP status codes
ippErrorValueFormat tags for attributes
ippTagValue