proposed change to soup_message_headers_get()

[Dan Winship <danw gnome org>]

http://bugzilla.gnome.org/show_bug.cgi?id=576760 points out that if a
server mistakenly sends two Content-Type headers, we return a bogus
value from soup_message_headers_get_content_type(). And in general, if
the headers contain more than one instance of a
supposed-to-be-single-valued header, then we mess up.

The problem soup_message_headers_get() is trying to solve is that the
HTTP spec allows certain headers to be sent either once as a
comma-separated list, or else multiple times with individual values, and
considers the two forms to be equivalent. So, eg, these are equivalent:

    Cache-Control: max-age=3600
    Cache-Control: private

    Cache-Control: max-age=3600, private

The trick is to expose this to applications in a way that (a) doesn't
suck to use, and (b) doesn't encourage them to mistakenly only look at
the first instance of the header and ignore the others. libsoup 2.2's
API failed at this (because soup_message_get_headers() was (a) and
soup_message_get_header() was (b)).

2.4's soup_message_headers_get() was supposed to solve this by making
apps only ever see the comma-separated form. But this ends up not
working either, because if the message is broken and contains multiple
copies of what should be a single-valued header, then we *want* to
ignore the extras, and concatenating them together is syntactically
correct. But libsoup has no way of knowing, in general, which headers
are single-valued and which are list-valued.

So, the patch in bug 576760, which I plan to commit for 2.26.1,
deprecated soup_message_headers_get(), and replaces it with two new
methods, soup_message_headers_get_one() and
soup_message_headers_get_list(), so the caller can explicitly state what
kind of header they're fetching, so libsoup can do the right thing in
either case.

Sending mail just to see if anyone has any objections / better ideas
before I commit it. (Oh, soup_message_headers_get() won't actually be
inside #ifndef LIBSOUP_DISABLE_DEPRECATED for 2.26.1, that will only
happen in 2.27.0.)

-- Dan