blob: 0c399aa58e1616cd50fdd710c0d5d70a033b0f25 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
Title: Migrating from libsoup 2
Slug: migrating-from-libsoup-2
# Migrating from libsoup 2
## Removed APIs
This is a list of APIs that have been removed:
- XML-RPC support.
- Handling of `file://` and `data://` URIs You should use [iface@Gio.File] for
the former and [func@uri_decode_data_uri] for the latter.
- Define aliases for property names You must use the string name of properties
directly which works in libsoup 2 already.
- `SoupSession:add-feature` and `SoupSession:add-feature-by-type` You must call
[method@Session.add_feature] and [method@Session.add_feature_by_type]
directly.
- `SoupRequest`: You should use [method@Session.send] or
[method@Session.send_async] methods.
- `SoupAddress` has been replaced with [class@Gio.InetAddress] and
[class@Gio.NetworkAddress].
- `SoupSocket` has been removed.
- `SoupProxyResolverDefault` is replaced by
[func@Gio.ProxyResolver.get_default].
- `SoupBuffer` has been replaced by [struct@GLib.Bytes] and
[struct@GLib.ByteArray].
- `SoupDate` has been replaced by `GDateTime`.
- `SoupSession:ssl-strict` has been removed in favor of using the
[signal@Message::accept-certificate] signal.
- `soup_session_cancel_message()` has been removed instead you
pass a [class@Gio.Cancellable] to APIs and call [method@Gio.Cancellable.cancel].
## Moved authenticate signal
The `SoupSession::authenticate` signal has been replaced by
[signal@Message::authenticate]. It now allows returning `TRUE` to signify if
you will handle authentication which allows for asynchronous handling.
## Structs are private
You can no longer directly access various structs such as [class@Message]. These are
now accessed by getters and setters. See below for direct
conversions:
<!-- TODO add links -->
<table>
<tr>
<th>Struct field</th>
<th>Getter/Setter function</th>
</tr>
<tr>
<td>SoupMessage.method</td>
<td>soup_message_get_method()</td>
</tr>
<tr>
<td>SoupMessage.status_code</td>
<td>soup_message_get_status()</td>
</tr>
<tr>
<td>SoupMessage.reason_phrase</td>
<td>soup_message_get_reason_phrase()</td>
</tr>
<tr>
<td>SoupMessage.uri</td>
<td>soup_message_get_uri(), soup_message_set_uri()</td>
</tr>
<tr>
<td>SoupMessage.request_headers</td>
<td>soup_message_get_request_headers()</td>
</tr>
<tr>
<td>SoupMessage.response_headers</td>
<td>soup_message_get_response_headers()</td>
</tr>
<tr>
<td>SoupMessage.request_body</td>
<td>soup_message_set_request_body(), soup_message_set_request_body_from_bytes()</td>
</tr>
<tr>
<td>SoupMessage.response_body</td>
<td>See section on IO</td>
</tr>
</table>
Similar struct changes exist for [struct@Cookie] but have very straightforward
replacements.
## URI type changed
The `SoupURI` type has been replaced with the [struct@GLib.Uri] type which has
some implications.
Creating a [struct@GLib.Uri] is generally as simple as `g_uri_parse (uri,
SOUP_HTTP_URI_FLAGS, NULL)`. You may want to add
`G_URI_FLAGS_PARSE_RELAXED` to accept input that used to be considered valid.
Note that unlike `SoupURI`, `GUri` is an immutable type so you cannot change the
contents of one after it has been constructed. We provide [func@uri_copy] to aid
in modifying them.
The equivalent behavior to `soup_uri_to_string (uri, FALSE)`
is `g_uri_to_string_partial (uri, G_URI_HIDE_PASSWORD)`.
Since `GUri` does not provide any function to check for equality
[func@uri_equal] still exists.
Sending a `OPTIONS` message with a path of `*` is no longer a valid URI and has
been replaced with [property@Message:is-options-ping].
## Status codes no longer used for internal errors
Previously [enum@Status] was used to hold libsoup errors
(`SOUP_STATUS_IS_TRANSPORT_ERROR()`). Now all of these errors are propagated up
through the normal [struct@GLib.Error] method on the various APIs to send
messages. Here is a mapping chart between the status codes and new errors:
<table>
<tr>
<th>Old Status Codes</th>
<th>New <code>GError</code></th>
</tr>
<tr>
<td><code>SOUP_STATUS_CANCELLED</code></td>
<td><code>G_IO_ERROR_CANCELLED</code></td>
</tr>
<tr>
<td><code>SOUP_STATUS_MALFORMED</code></td>
<td><code>SOUP_SESSION_ERROR_PARSING</code>, <code>SOUP_SESSION_ERROR_ENCODING</code></td>
</tr>
<tr>
<td><code>SOUP_STATUS_TOO_MANY_REDIRECTS</code></td>
<td><code>SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS</code></td>
</tr>
</table>
## All IO is now GIOStream-based
Previously there were ways to allow libsoup to read data into buffers and for
you to read from those buffers such as `SoupMessage:response-body`
`SoupMessage:response-body-data`, and `SoupServerMessage::got-chunk`.
libsoup no longer stores a buffer of data for you to read from and instead it
returns a [class@Gio.InputStream] which you read from using normal GIO APIs.
If you want to simply request a buffer and nothing more you can use the
[method@Session.send_and_read] or [method@Session.send_and_read_async] APIs.
This also applies to writing data where you can set a [class@Gio.InputStream]
using [method@Message.set_request_body] or use the convenience API
[method@Message.set_request_body_from_bytes] to use a [struct@GLib.Bytes]
buffer.
## Clarification on thread-safety
In libsoup 2 there was an attempt at making various APIs of the library
thread-safe. However this was never well tested, maintained, or documented.
In libsoup 3 it now behaves in line with other GObject libraries. Once you
create a [class@Session] all usage of that session must happen on the same
thread. You may create separate sessions per thread but in most use-cases you
should be using the async APIs which handle non-blocking IO for you.
|
