Header | cups/cups.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 structures for requests (messages sent to the CUPS
scheduler) and responses (messages sent back to your application from the
scheduler). The ipp_t
structure holds a
complete request or response and is allocated using the
ippNew
or
ippNewRequest
functions and
freed using the ippDelete
function.
The second structure is called
ipp_attribute_t
and holds a
single IPP attribute which consists of a group tag (group_tag
), a
value type tag (value_tag
), the attribute name (name
),
and 1 or more values (values[]
). Attributes are added to an
ipp_t
structure using one of the
ippAdd
functions. For example, use
ippAddString
to add a
"requesting-user-name" string attribute to a request:
ipp_t *request = ippNewRequest(IPP_GET_JOBS); 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_NAME, "requesting-user-name", NULL, cupsUser()); return (cupsDoRequest(CUPS_HTTP_DEFAULT, request, "/")); }
The cupsDoRequest
function frees
the request structure and returns an IPP response structure 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 = response->attrs; attr != NULL; attr = attr->next) if (attr->name == NULL) puts("--SEPARATOR--"); else puts(attr->name);
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; int job_id = 0; char *job_name = NULL; char *job_originating_user_name = NULL; puts("Job ID Owner Title"); puts("------ ---------------- ---------------------------------"); for (attr = response->attrs; attr != NULL; attr = attr->next) { /* Attributes without names are separators between jobs */ if (attr->name == NULL) { if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) 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(attr->name, "job-id") && attr->value_tag == IPP_TAG_INTEGER) job_id = attr->values[0].integer; else if (!strcmp(attr->name, "job-name") && attr->value_tag == IPP_TAG_NAME) job_name = attr->values[0].string.text; else if (!strcmp(attr->name, "job-originating-user-name") && attr->value_tag == IPP_TAG_NAME) job_originating_user_name = attr->values[0].string.text; } if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) 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_DEFAULT
0 on success, -1 on error
This function should be called in response to a HTTP_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_DEFAULT
NULL
for noneResponse data
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.
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_DEFAULT
Response data
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.
Do an IPP request.
ipp_t *cupsDoRequest (
http_t *http,
ipp_t *request,
const char *resource
);
CUPS_HTTP_DEFAULT
Response data
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.
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_DEFAULT
CUPS_TIMEOUT_DEFAULT
CUPS_INCLUDE_ALL
CUPS_EXCLUDE_NONE
Request 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_DEFAULT
HTTP status
This function returns HTTP_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_DEFAULT
HTTP status
This function returns HTTP_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_DEFAULT
Response or NULL
on HTTP error
Use this function to get the response for an IPP request sent using cupsSendDocument() or cupsSendRequest(). For requests that return additional data, use httpRead() after getting a successful response.
Return the last IPP status code.
ipp_status_t cupsLastError (void);
IPP status code from last request
Return the last IPP status-message.
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_DEFAULT
HTTP status
This function returns HTTP_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_DEFAULT
HTTP 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_DEFAULT
Bytes read, 0 on EOF, -1 on error
This function is used after cupsGetResponse() to read the PPD or document files for 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_DEFAULT
CUPS_LENGTH_VARIABLE
Initial HTTP status
Use httpWrite() to write any additional data (document, PPD file, etc.)
for the request, cupsGetResponse() to get the IPP response, and httpRead()
to read any additional data following the response. Only one request can be
sent/queued at a time.
Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the
request is not freed.
Write additional data after an IPP request.
http_status_t cupsWriteRequestData (
http_t *http,
const char *buffer,
size_t length
);
CUPS_HTTP_DEFAULT
HTTP_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.
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
Compare two addresses.
int httpAddrEqual (
const http_addr_t *addr1,
const http_addr_t *addr2
);
1 if equal, 0 if not
Return the length of the address in bytes.
int httpAddrLength (
const http_addr_t *addr
);
Length in bytes
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
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.
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
);
Connect to a HTTP server.
http_t *httpConnect (
const char *host,
int port
);
New HTTP connection
This function is deprecated - use httpConnectEncrypt
instead.
Connect to a HTTP server using encryption.
http_t *httpConnectEncrypt (
const char *host,
int port,
http_encryption_t encryption
);
New HTTP connection
Copy the credentials associated with an encrypted connection.
int httpCopyCredentials (
http_t *http,
cups_array_t **credentials
);
Status of call (0 = success)
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
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 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 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 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(). Otherwise, return the FQDN for the local system using both gethostname() and gethostbyname() to get the local hostname with domain.
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 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 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);
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)
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
Reconnect to a HTTP server.
int httpReconnect (
http_t *http
);
0 on success, non-zero on failure
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 Expect: header in a request.
void httpSetExpect (
http_t *http,
http_status_t expect
);
Currently only HTTP_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 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.
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)
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
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
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
Add a collection value.
ipp_attribute_t *ippAddCollection (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_t *value
);
New attribute
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
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
Add a integer attribute to an IPP message.
ipp_attribute_t *ippAddInteger (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t type,
const char *name,
int value
);
New attribute
Add an array of integer values.
ipp_attribute_t *ippAddIntegers (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t type,
const char *name,
int num_values,
const int *values
);
New attribute
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
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
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
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
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
Add a group separator to an IPP message.
ipp_attribute_t *ippAddSeparator (
ipp_t *ipp
);
New attribute
Add a language-encoded string to an IPP message.
ipp_attribute_t *ippAddString (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t type,
const char *name,
const char *charset,
const char *value
);
New attribute
Add language-encoded strings to an IPP message.
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
);
New attribute
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
);
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
Find the next named attribute in a request...
ipp_attribute_t *ippFindNextAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
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.
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 the default port number.
void ippSetPort (
int p
);
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
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 status codes
typedef enum http_status_e http_status_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);
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;
Attribute
typedef struct ipp_attribute_s ipp_attribute_t;
Finishings
typedef enum ipp_finish_e ipp_finish_t;
IPP IO Callback Function
typedef ssize_t (*ipp_iocb_t)(void *, ipp_uchar_t *, size_t);
Job states
typedef enum ipp_jstate_e ipp_jstate_t;
IPP operations
typedef enum ipp_op_e ipp_op_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;
Request Header
typedef union ipp_request_u ipp_request_t;
Resolution units
typedef enum ipp_res_e ipp_res_t;
IPP states
typedef enum ipp_state_e ipp_state_t;
Attribute Value
typedef struct ipp_s ipp_t;
IPP status codes
typedef typedef unsigned char ipp_uchar_t;
Format tags for attributes
typedef enum ipp_tag_e ipp_tag_t;
Attribute Value
typedef union ipp_value_u ipp_value_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;
};
Attribute
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];
};
IPP Request/Response/Notification
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;
int use;
};
Request Header
union ipp_request_u {
};
Attribute Value
union ipp_value_u {
char boolean;
ipp_t *collection;
ipp_uchar_t date[11];
int integer;
};
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
URI en/decode flags
URI separation status
HTTP version numbers
Finishings
Job states
IPP operations
Orientation values
Printer states
Qualities
Resolution units
IPP states
IPP status codes
Format tags for attributes