random usage notes from a libsoup newbie

["Benjamin Otte" <otte gnome org>]

So, I thought I'd post all the stuff that came to mind during my
recent experiences with libsoup. Maybe it's useful.

So, what have I done? I've made Swfdec [1] use libsoup for its http
handling. The Flash APIs for doing this are oriented at browser plugin
APIs. What I needed to implement in particular was an API that handles
the MovieClipLoader [2] and LoadVars [3] Flash objects. There is other
Flash objects that do HTTP access, but those aren't as demanding.

I used to use gnome-vfs for accessing HTTP before. The new libsoup
code is about half the size and does more. So in short: libsoup is
awesome to use. Create a session and a message and off you go. It's
great.
Of course there's stuff to nitpick about. Here it goes:

- Without the tutorial in the beginning of the docs I would have been
lost. The naming of the most important object seems a bit unfortunate;
a "message" to me is means something else.

- The docs itself are very sparse. What signal is emitted when in what
order and why? I wish every signal would be as well documented as
"authenticate" and "reauthenticate"

- It might be useful to note that libsoup requires threads to be
initialized. Maybe even provide a soup_init() function. Luckily, the
error message from glib when aborting was easy enough to read.

- I'd love if there was a default session, just like there exists a
default glib context. I have no clue if that makes sense.

- I'd really like to know more about what sessions are useful for.
Should there be one per application? One per thread? One per message?
Why would I want to create a new one?

- The API looks very old. I assume it was ported to GObject as an afterthought?

- The signal mechanism is duplicated. I'd wish it was only using glib
signals, probably with details, so I could connect to a
"got-headers::success" signal.

- I'm missing gobject properties. I wanted to connect to "notify::url"
and "notify::status", but neither the status code nor the url were
properties. (As a side note: I was fighting forwarding issues here and
wanted debugging output)

- I also get confused by the basic objects not being opaque. I'm used
to accessor functions for stuff like the status code instead of using
msg->status_code directly.

- SoupOwnership still confuses me. Can you please use refcounted
memory regions (like GStreamer, Swfdec [4] etc)?

- Since I needed progressive loading I connected to the got-chunk
signal and tried to use soup_message_pop_chunk(). I still haven't
figured out what that function does. Does it even work? Apparently I'm
supposed to use msg->response directly. At least that works fine.

Anyway, those are just nitpicks. It took me about an hour to do the
initial porting and another hour to make it work in corner cases,
which I consider a great thing for a network library.

Keep up the good work and pimp libsoup more, please. People need to
get rid of curl or gnome-vfs for http. ;)

Cheers,
Benjamin


[1] http://swfdec.freedesktop.org/
[2] http://www.brajeshwar.com/reference/as2/MovieClipLoader.html
[3] http://www.brajeshwar.com/reference/as2/LoadVars.html
[4] http://swfdec.freedesktop.org/documentation/swfdec/swfdec-SwfdecBuffer.html