First off, thanks for taking up this project! A fresh start seems sorely needed.

I am brand new to USB development, so I’ve been trying to figure out the best way to start playing with it, and libusb seemed like a good start (as opposed to kernel tinkering).

Unfortunately with libusb-0.1, documentation and examples are very, VERY weak. While I understand that writing a device driver is going to be device-specific, it simply doesn’t cut it for an API to not even explain its function parameters. I found it fairly frustrating trying to find any useful information, and this coming from a young (read Internet savvy), professional engineer and general code hacker.

By contrast, your documentation (http://libusb.sourceforge.net/api-1.0/) looks fantastic so far! Couple that with some great example code (maybe there are and I haven’t found them yet?), and your adoption rate will be huge.

I have a couple ideas for possible example code (maybe they’re not feasible - as I said, I’m just starting with this stuff):

- A “debug console”, intended for toying with USB devices, enumerating the bus and allowing you to select a device to connect to, trying to read/write it’s endpoints, etc.

- An example using a device that everybody is likely to have available, such as a mouse (HID) or USB thumb drive. It wouldn’t necessarily have to properly operate the device, but just perform some simple probing to show how to use the libusb-1.0 library.

I’d be willing to help in development of these examples, but I admit my C skills are so-so and my time limited.

Thanks again!
-Jeff

A number of libraries use this pattern; for example libgphoto2, gvfs file system backends, libhal, most GObject-based based libraries. One example of a pure C library that does this is libpolkit

http://hal.freedesktop.org/docs/PolicyKit/polkit-polkit-context.html

Hope this helps.

Sounds like a sensible change to make. It should not have too much impact on the API: the session context could be stored inside the devices and handles and automatically inferred internally, so only a few function interfaces would need modifications. For convenience the user could also pass a NULL context, which would indicate the first initialized context, or something like that. I’ll think more about the details then raise it on the mailing list.

For reference, could you give an example of an existing library that does this well?

Typically libraries provides a context object (e.g. LibUsbContext *libusb_init() or similar) and use this throughout the API. Under some circumstances you can get away with this. But since you have things like libusb_set_debug() it doesn’t look like you can get away with it; this call would affect all users of libusb in the process space; which (typically) is not desired (even though it’s probably not a big deal since it’s just debugging.. just trying to make a point).

Either way, it would probably make sense to at least document if your library is usable in such situations. Ideally it would be.