~ubuntu-branches/ubuntu/lucid/libsoup2.4/lucid

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new" title="soup_buffer_new ()">soup_buffer_new</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse">SoupMemoryUse</a> use,

gconstpointer data,

gsize length);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new-subbuffer" title="soup_buffer_new_subbuffer ()">soup_buffer_new_subbuffer</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *parent,

gsize offset,

gsize length);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()">soup_buffer_new_with_owner</a> (gconstpointer data,

gsize length,

gpointer owner,

GDestroyNotify owner_dnotify);

gpointer <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-get-owner" title="soup_buffer_get_owner ()">soup_buffer_get_owner</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()">soup_buffer_copy</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-free" title="soup_buffer_free ()">soup_buffer_free</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a>;

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-new" title="soup_message_body_new ()">soup_message_body_new</a> (void);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-free" title="soup_message_body_free ()">soup_message_body_free</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()">soup_message_body_set_accumulate</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

gboolean accumulate);

gboolean <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-get-accumulate" title="soup_message_body_get_accumulate ()">soup_message_body_get_accumulate</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()">soup_message_body_append</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse">SoupMemoryUse</a> use,

gconstpointer data,

gsize length);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()">soup_message_body_append_buffer</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-truncate" title="soup_message_body_truncate ()">soup_message_body_truncate</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()">soup_message_body_complete</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-flatten" title="soup_message_body_flatten ()">soup_message_body_flatten</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()">soup_message_body_get_chunk</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

goffset offset);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-got-chunk" title="soup_message_body_got_chunk ()">soup_message_body_got_chunk</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *chunk);

void <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-wrote-chunk" title="soup_message_body_wrote_chunk ()">soup_message_body_wrote_chunk</a> (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *chunk);

</pre>

</div>

<a name="libsoup-2.4-SoupMessageBody.description"></a><h2>Description</h2>

<p>

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> represents the request or response body of a

<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>.

</p>

<p>

In addition to <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>, libsoup also defines a "smaller"

data buffer type, <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>, which is primarily used as a

component of <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>. In particular, when using chunked

encoding to transmit or receive a message, each chunk is

100

represented as a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>.</p>

101

<p>

102

</p>

103

</div>

104

105

<a name="libsoup-2.4-SoupMessageBody.details"></a><h2>Details</h2>

106

107

<a name="SoupBuffer"></a><h3>SoupBuffer</h3>

108

<pre class="programlisting">typedef struct {

109

const char *data;

110

gsize length;

111

} SoupBuffer;

112

</pre>

113

<p>

114

A data buffer, generally used to represent a chunk of a

115

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>.

116

</p>

117

<p>

118

<em class="parameter"><code>data</code></em> is a <span class="type">char</span> because that's generally convenient; in some

119

situations you may need to cast it to <span class="type">guchar</span> or another type.</p>

120

<p>

121

</p>

122

123

124

<tbody>

125

<tr>

126

<td><p><span class="term">const char *<em class="structfield"><code><a name="SoupBuffer.data"></a>data</code></em>;</span></p></td>

127

<td> the data

128

</td>

129

</tr>

130

<tr>

131

<td><p><span class="term">gsize <em class="structfield"><code><a name="SoupBuffer.length"></a>length</code></em>;</span></p></td>

132

<td> length of <em class="parameter"><code>data</code></em>

133

</td>

134

</tr>

135

</tbody>

136

</table></div>

137

</div>

138

<hr>

139

140

<a name="SoupMemoryUse"></a><h3>enum SoupMemoryUse</h3>

141

<pre class="programlisting">typedef enum {

142

SOUP_MEMORY_STATIC,

143

SOUP_MEMORY_TAKE,

144

SOUP_MEMORY_COPY,

145

SOUP_MEMORY_TEMPORARY

146

} SoupMemoryUse;

147

</pre>

148

<p>

149

Describes how <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> should use the data passed in by the

150

caller.

151

</p>

152

<p>

153

See also <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a>, which allows to you create a

154

buffer containing data which is owned by another object.</p>

155

<p>

156

</p>

157

158

159

<tbody>

160

<tr>

161

<td><p><a name="SOUP-MEMORY-STATIC:CAPS"></a><span class="term"><code class="literal">SOUP_MEMORY_STATIC</code></span></p></td>

162

<td> The memory is statically allocated and

163

constant; libsoup can use the passed-in buffer directly and not

164

need to worry about it being modified or freed.

165

</td>

166

</tr>

167

<tr>

168

<td><p><a name="SOUP-MEMORY-TAKE:CAPS"></a><span class="term"><code class="literal">SOUP_MEMORY_TAKE</code></span></p></td>

169

<td> The caller has allocated the memory for the

170

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>'s use; libsoup will assume ownership of it and free it

171

(with <code class="function">g_free()</code>) when it is done with it.

172

</td>

173

</tr>

174

<tr>

175

<td><p><a name="SOUP-MEMORY-COPY:CAPS"></a><span class="term"><code class="literal">SOUP_MEMORY_COPY</code></span></p></td>

176

<td> The passed-in data belongs to the caller; the

177

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> will copy it into new memory, leaving the caller free

178

to reuse the original memory.

179

</td>

180

</tr>

181

<tr>

182

<td><p><a name="SOUP-MEMORY-TEMPORARY:CAPS"></a><span class="term"><code class="literal">SOUP_MEMORY_TEMPORARY</code></span></p></td>

183

<td> The passed-in data belongs to the caller,

184

but will remain valid for the lifetime of the <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>. The

185

difference between this and <em class="parameter"><code>SOUP_MEMORY_STATIC</code></em> is that if you copy

186

a <em class="parameter"><code>SOUP_MEMORY_TEMPORARY</code></em> buffer, it will make a copy of the memory

187

as well, rather than reusing the original memory.

188

</td>

189

</tr>

190

</tbody>

191

</table></div>

192

</div>

193

<hr>

194

195

<a name="soup-buffer-new"></a><h3>soup_buffer_new ()</h3>

196

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_buffer_new (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse">SoupMemoryUse</a> use,

197

gconstpointer data,

198

gsize length);</pre>

199

<p>

200

Creates a new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> containing <em class="parameter"><code>length</code></em> bytes from <em class="parameter"><code>data</code></em>.</p>

201

<p>

202

</p>

203

204

205

<tbody>

206

<tr>

207

208

<td> how <em class="parameter"><code>data</code></em> is to be used by the buffer

209

</td>

210

</tr>

211

<tr>

212

213

<td> data

214

</td>

215

</tr>

216

<tr>

217

<td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>

218

<td> length of <em class="parameter"><code>data</code></em>

219

</td>

220

</tr>

221

<tr>

222

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

223

<td> the new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>.

224

</td>

225

</tr>

226

</tbody>

227

</table></div>

228

</div>

229

<hr>

230

231

<a name="soup-buffer-new-subbuffer"></a><h3>soup_buffer_new_subbuffer ()</h3>

232

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_buffer_new_subbuffer (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *parent,

233

gsize offset,

234

gsize length);</pre>

235

<p>

236

237

<em class="parameter"><code>parent</code></em> starting at <em class="parameter"><code>offset</code></em>. (Normally this will not actually copy

238

any data, but will instead simply reference the same data as

239

<em class="parameter"><code>parent</code></em> does.)</p>

240

<p>

241

</p>

242

243

244

<tbody>

245

<tr>

246

<td><p><span class="term"><em class="parameter"><code>parent</code></em> :</span></p></td>

247

<td> the parent <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>

248

</td>

249

</tr>

250

<tr>

251

<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>

252

<td> offset within <em class="parameter"><code>parent</code></em> to start at

253

</td>

254

</tr>

255

<tr>

256

<td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>

257

<td> number of bytes to copy from <em class="parameter"><code>parent</code></em>

258

</td>

259

</tr>

260

<tr>

261

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

262

<td> the new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>.

263

</td>

264

</tr>

265

</tbody>

266

</table></div>

267

</div>

268

<hr>

269

270

<a name="soup-buffer-new-with-owner"></a><h3>soup_buffer_new_with_owner ()</h3>

271

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_buffer_new_with_owner (gconstpointer data,

272

gsize length,

273

gpointer owner,

274

GDestroyNotify owner_dnotify);</pre>

275

<p>

276

277

the <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> is freed, it will call <em class="parameter"><code>owner_dnotify</code></em>, passing

278

<em class="parameter"><code>owner</code></em> to it. You must ensure that <em class="parameter"><code>data</code></em> will remain valid until

279

<em class="parameter"><code>owner_dnotify</code></em> is called.

280

</p>

281

<p>

282

For example, you could use this to create a buffer containing data

283

returned from libxml without needing to do an extra copy:

284

</p>

285

<p>

286

</p>

287

288

xmlDocDumpMemory (doc, &xmlbody, &len);

289

return soup_buffer_new_with_owner (xmlbody, len, xmlbody,

290

(GDestroyNotify)xmlFree);

291

</pre></div>

292

<p>

293

</p>

294

<p>

295

In this example, <em class="parameter"><code>data</code></em> and <em class="parameter"><code>owner</code></em> are the same, but in other cases

296

they would be different (eg, <em class="parameter"><code>owner</code></em> would be a object, and <em class="parameter"><code>data</code></em>

297

would be a pointer to one of the object's fields).</p>

298

<p>

299

</p>

300

301

302

<tbody>

303

<tr>

304

305

<td> data

306

</td>

307

</tr>

308

<tr>

309

<td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>

310

<td> length of <em class="parameter"><code>data</code></em>

311

</td>

312

</tr>

313

<tr>

314

<td><p><span class="term"><em class="parameter"><code>owner</code></em> :</span></p></td>

315

<td> pointer to an object that owns <em class="parameter"><code>data</code></em>

316

</td>

317

</tr>

318

<tr>

319

<td><p><span class="term"><em class="parameter"><code>owner_dnotify</code></em> :</span></p></td>

320

<td> a function to free/unref <em class="parameter"><code>owner</code></em> when the buffer is

321

freed

322

</td>

323

</tr>

324

<tr>

325

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

326

<td> the new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>.

327

</td>

328

</tr>

329

</tbody>

330

</table></div>

331

</div>

332

<hr>

333

334

<a name="soup-buffer-get-owner"></a><h3>soup_buffer_get_owner ()</h3>

335

<pre class="programlisting">gpointer soup_buffer_get_owner (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);</pre>

336

<p>

337

Gets the "owner" object for a buffer created with

338

<a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a>.</p>

339

<p>

340

</p>

341

342

343

<tbody>

344

<tr>

345

<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>

346

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> created with <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a>

347

</td>

348

</tr>

349

<tr>

350

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

351

<td> the owner pointer

352

</td>

353

</tr>

354

</tbody>

355

</table></div>

356

</div>

357

<hr>

358

359

<a name="soup-buffer-copy"></a><h3>soup_buffer_copy ()</h3>

360

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_buffer_copy (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);</pre>

361

<p>

362

Makes a copy of <em class="parameter"><code>buffer</code></em>. In reality, <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> is a refcounted

363

type, and calling <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a> will normally just increment

364

the refcount on <em class="parameter"><code>buffer</code></em> and return it. However, if <em class="parameter"><code>buffer</code></em> was

365

created with <a class="link" href="libsoup-2.4-SoupMessageBody.html#SOUP-MEMORY-TEMPORARY:CAPS"><span class="type">SOUP_MEMORY_TEMPORARY</span></a> memory, then <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a>

366

will actually return a copy of it, so that the data in the copy

367

will remain valid after the temporary buffer is freed.</p>

368

<p>

369

</p>

370

371

372

<tbody>

373

<tr>

374

<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>

375

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>

376

</td>

377

</tr>

378

<tr>

379

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

380

<td> the new (or newly-reffed) buffer

381

</td>

382

</tr>

383

</tbody>

384

</table></div>

385

</div>

386

<hr>

387

388

<a name="soup-buffer-free"></a><h3>soup_buffer_free ()</h3>

389

<pre class="programlisting">void soup_buffer_free (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);</pre>

390

<p>

391

Frees <em class="parameter"><code>buffer</code></em>. (In reality, as described in the documentation for

392

<a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a>, this is actually an "unref" operation, and may

393

or may not actually free <em class="parameter"><code>buffer</code></em>.)</p>

394

<p>

395

</p>

396

397

398

399

<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>

400

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>

401

</td>

402

</tr></tbody>

403

</table></div>

404

</div>

405

<hr>

406

407

<a name="SoupMessageBody"></a><h3>SoupMessageBody</h3>

408

<pre class="programlisting">typedef struct {

409

const char *data;

410

goffset length;

411

} SoupMessageBody;

412

</pre>

413

<p>

414

A <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> request or response body.

415

</p>

416

<p>

417

Note that while <em class="parameter"><code>length</code></em> always reflects the full length of the

418

message body, <em class="parameter"><code>data</code></em> is normally <a href="/opt/jhbuild/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>, and will only be filled in

419

after <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-flatten" title="soup_message_body_flatten ()"><code class="function">soup_message_body_flatten()</code></a> is called. For client-side

420

messages, this automatically happens for the response body after it

421

has been fully read, unless you set the

422

<a class="link" href="SoupMessage.html#SOUP-MESSAGE-OVERWRITE-CHUNKS:CAPS"><code class="literal">SOUP_MESSAGE_OVERWRITE_CHUNKS</code></a> flags. Likewise, for server-side

423

messages, the request body is automatically filled in after being

424

read.

425

</p>

426

<p>

427

As an added bonus, when <em class="parameter"><code>data</code></em> is filled in, it is always terminated

428

with a '\0' byte (which is not reflected in <em class="parameter"><code>length</code></em>).</p>

429

<p>

430

</p>

431

432

433

<tbody>

434

<tr>

435

<td><p><span class="term">const char *<em class="structfield"><code><a name="SoupMessageBody.data"></a>data</code></em>;</span></p></td>

436

<td> the data

437

</td>

438

</tr>

439

<tr>

440

<td><p><span class="term">goffset <em class="structfield"><code><a name="SoupMessageBody.length"></a>length</code></em>;</span></p></td>

441

<td> length of <em class="parameter"><code>data</code></em>

442

</td>

443

</tr>

444

</tbody>

445

</table></div>

446

</div>

447

<hr>

448

449

<a name="soup-message-body-new"></a><h3>soup_message_body_new ()</h3>

450

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> * soup_message_body_new (void);</pre>

451

<p>

452

Creates a new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>. <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> uses this internally; you

453

will not normally need to call it yourself.</p>

454

<p>

455

</p>

456

457

458

459

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

460

<td> a new <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>.

461

</td>

462

</tr></tbody>

463

</table></div>

464

</div>

465

<hr>

466

467

<a name="soup-message-body-free"></a><h3>soup_message_body_free ()</h3>

468

<pre class="programlisting">void soup_message_body_free (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);</pre>

469

<p>

470

Frees <em class="parameter"><code>body</code></em>. You will not normally need to use this, as

471

<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> frees its associated message bodies automatically.</p>

472

<p>

473

</p>

474

475

476

477

478

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

479

</td>

480

</tr></tbody>

481

</table></div>

482

</div>

483

<hr>

484

485

<a name="soup-message-body-set-accumulate"></a><h3>soup_message_body_set_accumulate ()</h3>

486

<pre class="programlisting">void soup_message_body_set_accumulate (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

487

gboolean accumulate);</pre>

488

<p>

489

Sets or clears the accumulate flag on <em class="parameter"><code>body</code></em>. (The default value is

490

<code class="literal">TRUE</code>.) If set to <code class="literal">FALSE</code>, <em class="parameter"><code>body</code></em>'s <code class="literal">data</code> field will not be filled in

491

after the body is fully sent/received, and the chunks that make up

492

<em class="parameter"><code>body</code></em> may be discarded when they are no longer needed.

493

</p>

494

<p>

495

In particular, if you set this flag to <code class="literal">FALSE</code> on an "incoming"

496

message body (that is, the <code class="literal">response_body</code> of a client-side message,

497

or <code class="literal">request_body</code> of a server-side message), this will cause each

498

chunk of the body to be discarded after its corresponding

499

<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title='The "got-chunk" signal'><span class="type">"got_chunk"</span></a> signal is emitted. (This is equivalent to

500

setting the deprecated <a class="link" href="SoupMessage.html#SOUP-MESSAGE-OVERWRITE-CHUNKS:CAPS"><code class="literal">SOUP_MESSAGE_OVERWRITE_CHUNKS</code></a> flag on the

501

message.)

502

</p>

503

<p>

504

If you set this flag to <code class="literal">FALSE</code> on the <code class="literal">response_body</code> of a

505

server-side message, it will cause each chunk of the body to be

506

discarded after its corresponding <a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title='The "wrote-chunk" signal'><span class="type">"wrote_chunk"</span></a> signal

507

is emitted.

508

</p>

509

<p>

510

(If you set the flag to <code class="literal">FALSE</code> on the <code class="literal">request_body</code> of a

511

client-side message, it will block the accumulation of chunks into

512

<em class="parameter"><code>body</code></em>'s <code class="literal">data</code> field, but it will not cause the chunks to be

513

discarded after being written like in the server-side

514

<code class="literal">response_body</code> case, because the request body needs to be kept

515

around in case the request needs to be sent a second time due to

516

redirection or authentication.)</p>

517

<p>

518

</p>

519

520

521

<tbody>

522

<tr>

523

524

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

525

</td>

526

</tr>

527

<tr>

528

<td><p><span class="term"><em class="parameter"><code>accumulate</code></em> :</span></p></td>

529

<td> whether or not to accumulate body chunks in <em class="parameter"><code>body</code></em>

530

</td>

531

</tr>

532

</tbody>

533

</table></div>

534

<p class="since">Since 2.4.1</p>

535

</div>

536

<hr>

537

538

<a name="soup-message-body-get-accumulate"></a><h3>soup_message_body_get_accumulate ()</h3>

539

<pre class="programlisting">gboolean soup_message_body_get_accumulate (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);</pre>

540

<p>

541

Gets the accumulate flag on <em class="parameter"><code>body</code></em>; see

542

<a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> for details.</p>

543

<p>

544

</p>

545

546

547

<tbody>

548

<tr>

549

550

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

551

</td>

552

</tr>

553

<tr>

554

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

555

<td> the accumulate flag for <em class="parameter"><code>body</code></em>.

556

557

</td>

558

</tr>

559

</tbody>

560

</table></div>

561

<p class="since">Since 2.4.1</p>

562

</div>

563

<hr>

564

565

<a name="soup-message-body-append"></a><h3>soup_message_body_append ()</h3>

566

<pre class="programlisting">void soup_message_body_append (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

567

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse">SoupMemoryUse</a> use,

568

gconstpointer data,

569

gsize length);</pre>

570

<p>

571

Appends <em class="parameter"><code>length</code></em> bytes from <em class="parameter"><code>data</code></em> to <em class="parameter"><code>body</code></em> according to <em class="parameter"><code>use</code></em>.</p>

572

<p>

573

</p>

574

575

576

<tbody>

577

<tr>

578

579

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

580

</td>

581

</tr>

582

<tr>

583

584

585

</td>

586

</tr>

587

<tr>

588

589

<td> data to append

590

</td>

591

</tr>

592

<tr>

593

<td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>

594

<td> length of <em class="parameter"><code>data</code></em>

595

</td>

596

</tr>

597

</tbody>

598

</table></div>

599

</div>

600

<hr>

601

602

<a name="soup-message-body-append-buffer"></a><h3>soup_message_body_append_buffer ()</h3>

603

<pre class="programlisting">void soup_message_body_append_buffer (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

604

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *buffer);</pre>

605

<p>

606

Appends the data from <em class="parameter"><code>buffer</code></em> to <em class="parameter"><code>body</code></em>. (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> uses

607

<span class="type">SoupBuffers</span> internally, so this is normally a constant-time

608

operation that doesn't actually require copying the data in

609

<em class="parameter"><code>buffer</code></em>.)</p>

610

<p>

611

</p>

612

613

614

<tbody>

615

<tr>

616

617

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

618

</td>

619

</tr>

620

<tr>

621

<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>

622

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>

623

</td>

624

</tr>

625

</tbody>

626

</table></div>

627

</div>

628

<hr>

629

630

<a name="soup-message-body-truncate"></a><h3>soup_message_body_truncate ()</h3>

631

<pre class="programlisting">void soup_message_body_truncate (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);</pre>

632

<p>

633

Deletes all of the data in <em class="parameter"><code>body</code></em>.</p>

634

<p>

635

</p>

636

637

638

639

640

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

641

</td>

642

</tr></tbody>

643

</table></div>

644

</div>

645

<hr>

646

647

<a name="soup-message-body-complete"></a><h3>soup_message_body_complete ()</h3>

648

<pre class="programlisting">void soup_message_body_complete (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);</pre>

649

<p>

650

Tags <em class="parameter"><code>body</code></em> as being complete; Call this when using chunked encoding

651

after you have appended the last chunk.</p>

652

<p>

653

</p>

654

655

656

657

658

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

659

</td>

660

</tr></tbody>

661

</table></div>

662

</div>

663

<hr>

664

665

<a name="soup-message-body-flatten"></a><h3>soup_message_body_flatten ()</h3>

666

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_message_body_flatten (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body);</pre>

667

<p>

668

Fills in <em class="parameter"><code>body</code></em>'s data field with a buffer containing all of the

669

data in <em class="parameter"><code>body</code></em> (plus an additional '\0' byte not counted by <em class="parameter"><code>body</code></em>'s

670

length field).</p>

671

<p>

672

</p>

673

674

675

<tbody>

676

<tr>

677

678

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

679

</td>

680

</tr>

681

<tr>

682

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

683

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> containing the same data as <em class="parameter"><code>body</code></em>.

684

(You must free this buffer if you do not want it.)

685

</td>

686

</tr>

687

</tbody>

688

</table></div>

689

</div>

690

<hr>

691

692

<a name="soup-message-body-get-chunk"></a><h3>soup_message_body_get_chunk ()</h3>

693

<pre class="programlisting"><a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> * soup_message_body_get_chunk (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

694

goffset offset);</pre>

695

<p>

696

Gets a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> containing data from <em class="parameter"><code>body</code></em> starting at <em class="parameter"><code>offset</code></em>.

697

The size of the returned chunk is unspecified. You can iterate

698

through the entire body by first calling

699

700

successive call, increment the offset by the length of the

701

previously-returned chunk.

702

</p>

703

<p>

704

If <em class="parameter"><code>offset</code></em> is greater than or equal to the total length of <em class="parameter"><code>body</code></em>,

705

then the return value depends on whether or not

706

<a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()"><code class="function">soup_message_body_complete()</code></a> has been called or not; if it has,

707

then <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a> will return a 0-length chunk

708

(indicating the end of <em class="parameter"><code>body</code></em>). If it has not, then

709

<a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a> will return <a href="/opt/jhbuild/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a> (indicating that

710

<em class="parameter"><code>body</code></em> may still potentially have more data, but that data is not

711

currently available).</p>

712

<p>

713

</p>

714

715

716

<tbody>

717

<tr>

718

719

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

720

</td>

721

</tr>

722

<tr>

723

<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>

724

<td> an offset

725

</td>

726

</tr>

727

<tr>

728

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

729

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a>, or <a href="/opt/jhbuild/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>.

730

</td>

731

</tr>

732

</tbody>

733

</table></div>

734

</div>

735

<hr>

736

737

<a name="soup-message-body-got-chunk"></a><h3>soup_message_body_got_chunk ()</h3>

738

<pre class="programlisting">void soup_message_body_got_chunk (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

739

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *chunk);</pre>

740

<p>

741

Handles the <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> part of receiving a chunk of data from

742

the network. Normally this means appending <em class="parameter"><code>chunk</code></em> to <em class="parameter"><code>body</code></em>, exactly

743

as with <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer()</code></a>, but if you have set

744

<em class="parameter"><code>body</code></em>'s accumulate flag to <code class="literal">FALSE</code>, then that will not happen.

745

</p>

746

<p>

747

This is a low-level method which you should not normally need to

748

use.</p>

749

<p>

750

</p>

751

752

753

<tbody>

754

<tr>

755

756

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

757

</td>

758

</tr>

759

<tr>

760

<td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>

761

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> received from the network

762

</td>

763

</tr>

764

</tbody>

765

</table></div>

766

<p class="since">Since 2.4.1</p>

767

</div>

768

<hr>

769

770

<a name="soup-message-body-wrote-chunk"></a><h3>soup_message_body_wrote_chunk ()</h3>

771

<pre class="programlisting">void soup_message_body_wrote_chunk (<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody">SoupMessageBody</a> *body,

772

<a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer">SoupBuffer</a> *chunk);</pre>

773

<p>

774

Handles the <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> part of writing a chunk of data to the

775

network. Normally this is a no-op, but if you have set <em class="parameter"><code>body</code></em>'s

776

accumulate flag to <code class="literal">FALSE</code>, then this will cause <em class="parameter"><code>chunk</code></em> to be

777

discarded to free up memory.

778

</p>

779

<p>

780

This is a low-level method which you should not need to use, and

781

there are further restrictions on its proper use which are not

782

documented here.</p>

783

<p>

784

</p>

785

786

787

<tbody>

788

<tr>

789

790

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupMessageBody" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>

791

</td>

792

</tr>

793

<tr>

794

<td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>

795

<td> a <a class="link" href="libsoup-2.4-SoupMessageBody.html#SoupBuffer" title="SoupBuffer"><span class="type">SoupBuffer</span></a> returned from <a class="link" href="libsoup-2.4-SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a>

796

</td>

797

</tr>

798

</tbody>

799

</table></div>

800

<p class="since">Since 2.4.1</p>

801

</div>

802

</div>

803

804

805

<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>

806

</div>

807

</div>

808

809

<hr>

810

Generated by GTK-Doc V1.12</div>

811

</body>

812

</html>

Older »