Question regarding libcups3 api

[soumyaDghosh]

libcups3 adds a new API about authentication. How does it work? Can I authenticate anything? How does it authenticate a job? Can you kindly clarify a bit about that API?

[tillkamppeter]

@michaelrsweet ^^

[soumyaDghosh]

Another question, related to the APIs. How does one properly extract a collection? ippGetCollection seems to return an ipp_t which is an IPPRequest or IPPResponse, how should we parse them?

[michaelrsweet]

I think the hard question comes here, is a user facing program supposed to manage the authentications manually? If, not, then what's the use case of that API?

A user facing program that uses the low-level CUPS APIs is absolutely supposed to handle authentication. You do this by setting a password callback (cupsSetPasswordCB) and showing UI for entering a username and password. However, since most applications use a higher-level toolkit of some sort (Qt, GTK+, SwiftUI/Cocoa on macOS, etc.) you don't need to worry about it because you aren't using the CUPS API to print.

Also, as you mentioned connecting to a destination using the API cupsConnectDest, how different is it from httpConnect? Is it like when connecting using httpConnect you connect to a server, that acts as a pool of destionations, and when connecting to a destination directly, only that particular destination and the related resouces, are available?

cupsConnectDest works with a destination (cups_dest_t pointer) while httpConnect and friends work with URIs, hostnames, ports, etc. More specifically, the CUPS "dest" APIs are concerned with communicating with a printer while the "http" APIs are concerned with communicating with a generic HTTP service. (IPP is layered on HTTP, which is why CUPS provides both APIs...)

Printer pools (what are called "classes" in CUPS and the historical System V "lp" spooler) are NOT managed via HTTP connections, but are an entirely separate thing. IPP calls this kind of thing "fan out". A CUPS destination that is associated with multiple printers is called a class, and you communicate with the class using the CUPS "dest" APIs. The scheduler (cupsd) takes care of distributing print jobs to each of the printers in the class for you.

A follow-up about the API, what's the difference between a cups_file_t and an ipp_file_t? What's the use of cups_file_t?

The CUPS "file" APIs (which use cups_file_t pointers) is an alternative to the C stdio APIs (fopen, fclose, etc.) that is not limited to 256 open files. Aside from providing most of the same functionality, they also support gzip compression/decompression and simple socket I/O.

The CUPS "IPP file" APIs (which use ipp_file_t pointers) support file encoding/decoding of IPP messages/attributes and associated information. They specifically exist to support the ipptool and ippeveprinter programs in the libcups project as well as several other programs in related projects (ippserver in the PWG's ippsample project, for example).

Another question, related to the APIs. How does one properly extract a collection? ippGetCollection seems to return an ipp_t which is an IPPRequest or IPPResponse, how should we parse them?

The ipp_t type abstracts an IPP message or collection value. So if you have a collection value you can use the ippFindAttribute and other IPP functions to look at the member attributes in the collection.

[soumyaDghosh]

A user facing program that uses the low-level CUPS APIs is absolutely supposed to handle authentication. You do this by setting a password callback (cupsSetPasswordCB) and showing UI for entering a username and password. However, since most applications use a higher-level toolkit of some sort (Qt, GTK+, SwiftUI/Cocoa on macOS, etc.) you don't need to worry about it because you aren't using the CUPS API to print.

Since, pycups can also be used by these toolkits themselves, so, I think I'll have to implement these low level APIs. Thanks a lot for the clarification.

cupsConnectDest works with a destination (cups_dest_t pointer) while httpConnect and friends work with URIs, hostnames, ports, etc. More specifically, the CUPS "dest" APIs are concerned with communicating with a printer while the "http" APIs are concerned with communicating with a generic HTTP service. (IPP is layered on HTTP, which is why CUPS provides both APIs...)

This was also my initial thought, but how can a program or even libcups distiguish, that an http connection is obtained using httConnect or is it obtained using cupsConnectDest. http looks like an opaque struct and I couldn't find a way to verify its integrity or type safety.

If someone tries to connect to a destination using cupsConnectDest, obtains an http object from that connect and then reuses it for something related to http connection, or vice-e-versa, will it work? I tried this,

import cups
from cups import ffi, lib
conn = cups.Connection() #creates an http connection using httpConnect
res=ffi.new("char [256]")
h = lib.cupsConnectDest(dest.ffi_value, cups.enums.cups.CUPSDestFlags.NONE.value, 3000, ffi.NULL, res, ffi.sizeof(res), ffi.NULL, ffi.NULL)
print(lib.cupsGetPassword(b"Enter password", h, b"GET", ffi.NULL))
print(lib.cupsGetPassword(b"Enter password", conn.http, b"GET", ffi.NULL))

According to the logic, I should have not obtained anything in atleast one case? But, in both case I got the prompt to enter password and got the value that I entered.

>>> lib.cupsGetPassword(b"Enter password", h, b"GET", ffi.NULL)
Enter password ******** 
<cdata 'char *' 0x24d00f01>
>>> lib.cupsGetPassword(b"Enter password", conn.http, b"GET", ffi.NULL)
Enter password ********
<cdata 'char *' 0x24d00f01>

Can you kindly clarify a bit about this behavior?

The CUPS "file" APIs (which use cups_file_t pointers) is an alternative to the C stdio APIs (fopen, fclose, etc.) that is not limited to 256 open files. Aside from providing most of the same functionality, they also support gzip compression/decompression and simple socket I/O.

So, this is basically just a better way of handling files and doesn't have anything to do with the CUPs backend? In that case, as python has a lot of better alternatives, do you think I can skip this?

The CUPS "IPP file" APIs (which use ipp_file_t pointers) support file encoding/decoding of IPP messages/attributes and associated information. They specifically exist to support the ipptool and ippeveprinter programs in the libcups project as well as several other programs in related projects (ippserver in the PWG's ippsample project, for example).

Is there any use case of those in user facing applications? Do you think, from the context of pycups, we need to implement them?

The ipp_t type abstracts an IPP message or collection value. So if you have a collection value you can use the ippFindAttribute and other IPP functions to look at the member attributes in the collection.

So, an IPP Collection, is just an array or list of IPPAttributes?

[michaelrsweet]

This was also my initial thought, but how can a program or even libcups distiguish, that an http connection is obtained using httConnect or is it obtained using cupsConnectDest. http looks like an opaque struct and I couldn't find a way to verify its integrity or type safety.

A HTTP connection is a HTTP connection, there is no difference for that. However, when you use httpConnect you are connecting to a specific address and port. httpConnectURI takes a URI that you supply. But cupsConnectDest connects to either the local print queue or (if CUPS_DEST_FLAGS_DEVICE is set in the flags argument) the actual IPP printer. It is up to the application to remember the context to determine whether you can pass the HTTP connection to the cupsCreateDestJob, cupsStartDestDocument, etc. functions. Similarly, if the HTTP connection is to the same host and port as a resource (say, an icon file) then you can reuse the connection from cupsConnectDest with the regular HTTP functions.

WRT cupsGetPassword, that function does not perform authentication, it simply gets a password from the user. A password callback might use the supplied HTTP connection, method, and/or resource to lookup a saved password and return that instead of asking for a password.

So, this is basically just a better way of handling files and doesn't have anything to do with the CUPs backend? In that case, as python has a lot of better alternatives, do you think I can skip this?

That's up to you but probably yes.

(also for the ippFile APIs)

So, an IPP Collection, is just an array or list of IPPAttributes?

It is a dictionary of key/value pairs. In JSON/Javascript you'd call it an object.

And collections can be nested...

[soumyaDghosh]

WRT cupsGetPassword, that function does not perform authentication, it simply gets a password from the user. A password callback might use the supplied HTTP connection, method, and/or resource to lookup a saved password and return that instead of asking for a password.

Hi, I only used cupsGetPassword as a simple example, but I understand the idea now. Essentially, it is my responsibility to ensure which connection can be passed where.

So the distinction is: for any API that uses the http connection to communicate with a destination, we can use the http object obtained from cupsConnectDest else we'll have to create the connection using httpConnect. And I presume it must also be the same destination for which that connection was originally made? Please let me know if my assumption is wrong about this.

It is a dictionary of key/value pairs. In JSON/Javascript you'd call it an object.

And collections can be nested...

Thanks a lot, got it. In python, I should create JSon objects in that case.

[michaelrsweet]

So the distinction is: for any API that uses the http connection to communicate with a destination, we can use the http object obtained from cupsConnectDest else we'll have to create the connection using httpConnect. And I presume it must also be the same destination for which that connection was originally made? Please let me know if my assumption is wrong about this.

Yes, that is the safe assumption. Also, the CUPS dest APIs allow NULL for the HTTP connection, at which point it uses a per-thread connection behind the scenes (typically a domain socket to the local cupsd in CUPS 2.x or cupslocald in CUPS 3.x).

[michaelrsweet]

The BSD socket API doesn't offer a lot of options, and even then you are just seeing the connection state from your end - thanks to the wonders of networking you may not yet be aware that the other side has connected or disconnected from you. :/

[soumyaDghosh]

In that case, what could be the actual difference between a scenario where msec = 0 and one where msec is non-zero? I don’t really notice any degradation in the connection’s capabilities in either case.

[michaelrsweet]

Functionally there is no difference between a connected and unconnected (msec=0) http_t pointer, as the underlying code will automatically (re)connect as needed to send a request.

[soumyaDghosh]

Can you kindly explain a bit about the len argument which says Number of bytes to read for the cupsRasterReadPixels api? Where can we obtain this length?

[michaelrsweet]

This is the cupsBytesPerLine value from the page header.

[soumyaDghosh]

Hi @michaelrsweet how this api httpGetField is supposed to work? What is the http_field_t stands for? Can you kindly explain us about this API a bit?

[michaelrsweet]

httpGetField retrieves the value of a HTTP request or response field. The http_field_t enumeration defines the HTTP_FIELD_xxx values which correspond to each of the possible headers that are supported by libcups.

[soumyaDghosh]

@michaelrsweet Looks like there is no doc on https://openprinting.github.io/cups/libcups/cupspm.html#http_version_t which is the return type for the method httpGetVersion

[michaelrsweet]

The documentation was disabled years ago since most applications have no need to use httpGetVersion - it is only really needed for HTTP servers...

I'll remove the "exclude" directive from the header so that the type is documented.