cpp-netlib.github.com/0.9.0/reference_http_client.html at master · cpp-netlib/cpp-netlib.github.com

History

460 lines (433 loc) · 23.8 KB

Raw

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

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>HTTP Client API — cpp-netlib v0.9 documentation</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '',

VERSION: '0.9',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true

};

</script>

var _gaq = _gaq || [];

_gaq.push(['_setAccount', 'UA-19815738-1']);

_gaq.push(['_trackPageview']);

(function() {

var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;

ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';

var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);

})();

</script>

</head>

<body>

<h1><a href="index.html">cpp-netlib v0.9 documentation</a></h1>

« <a href="reference.html" title="Reference Manual">previous</a>

</div>

<h1>HTTP Client API<a class="headerlink" href="#http-client-api" title="Permalink to this headline">¶</a></h1>

<h2>General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>

<p><tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> includes and implements a number of HTTP clients that you can

use and embed in your own applications. All of the HTTP client implementations:</p>

<li><strong>Cannot be copied.</strong> This means you may have to store instances of the

clients in dynamic memory if you intend to use them as function parameters

or pass them around in smart pointers or by reference.</li>

<li><strong>Assume that requests made are independent of each other.</strong> There currently

is no cookie or session management system built-in to cpp-netlib’s HTTP client

implementations.</li>

<li><strong>Are header-only and are compiled-into your application.</strong> Future releases in

case you want to upgrade the implementation you are using in your application

will be distributed as header-only implementations, which means you have to

re-compile your application to use a newer version of the implementations.</li>

</ul>

</div></blockquote>

<p>The HTTP clients all share the same API, but the internals are documented in

terms of what is different and what to expect with the different

implementations.</p>

</div>

<h2>Implementations<a class="headerlink" href="#implementations" title="Permalink to this headline">¶</a></h2>

<p>There is a single user-facing template class named <tt class="docutils literal"><span class="pre">basic_client</span></tt> which takes

three template parameters:</p>

<li><strong>Tag</strong> - which static tag you choose that defines the behavior of the client.</li>

<li><strong>http_version_major</strong> - an unsigned int that defines the HTTP major version

number, this directly affects the HTTP messages sent by the client.</li>

<li><strong>http_version_minor</strong> - an unsigned int that defines the HTTP minor version

number.</li>

</ul>

</div></blockquote>

<p>There are two major different class of implementations of the <tt class="docutils literal"><span class="pre">basic_client</span></tt>

template that depend on which tag you choose: <a class="reference internal" href="#synchronous-clients">Synchronous Clients</a> and

<a class="reference internal" href="#asynchronous-clients">Asynchronous Clients</a>. These two different classes are described in their own

sections following this one. What follows is a table of all tags supported by

the HTTP client implementation provided by <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>.</p>

</colgroup>

<th class="head">Description</th>

</tr>

</thead>

<tr><td>http_default_8bit_tcp_resolve</td>

<td>This is the default HTTP implementation tag

that resolves addresses with a TCP resolver

and provides a synchronous/blocking HTTP

client interface.</td>

</tr>

<tr><td>http_default_8bit_udp_resolve</td>

<td>This is similar to the above tag except that

it specifies the HTTP client to use a UDP

resolver. It also provides a synchronous/

blocking HTTP client interface.</td>

</tr>

<tr><td>http_keepalive_8bit_tcp_resolve</td>

<td>This tag specifies that the HTTP client by

default will keep connections to the server

alive. It only makes sense if the

<tt class="docutils literal"><span class="pre">version_major</span></tt> and <tt class="docutils literal"><span class="pre">version_minor</span></tt> are

both <tt class="docutils literal"><span class="pre">1</span></tt>, to indicate HTTP 1.1. This tag

causes the HTTP client to resolve using a

TCP resolver and provides a synchronous/

blocking HTTP client interface.</td>

</tr>

<tr><td>http_keepalive_8bit_udp_resolve</td>

<td>This is similar to the above tag except that

it specifies the HTTP client to use a UDP

resolver. It also provides a synchronous/

blocking HTTP client interface.</td>

</tr>

<tr><td>http_async_8bit_tcp_resolve</td>

<td>This tag provides an active HTTP client

object implementation that uses a TCP

resolver. Response objects returned will

encapsulate a number of <a class="reference external" href="http://www.boost.org/libs/thread">Boost.Thread</a>

shared futures to hold values. Users don’t

have to see this as they are implementation

details.</td>

</tr>

<tr><td>http_async_8bit_udp_resolve</td>

<td>This is similar to the above tag except that

specifies the HTTP client to use a UDP

resolver.</td>

</tr>

</tbody>

</table>

<p>In the above table the tags follow a pattern for describing the behavior

introduced by the tags. This pattern is shown below:</p>

<p>For example, the tag <tt class="docutils literal"><span class="pre">http_default_8bit_tcp_resolve</span></tt> indicates the protocol

<tt class="docutils literal"><span class="pre">http</span></tt>, a modifier <tt class="docutils literal"><span class="pre">default</span></tt>, a character width of <tt class="docutils literal"><span class="pre">8bit</span></tt>, and a resolve

strategy of <tt class="docutils literal"><span class="pre">tcp_resolve</span></tt>.</p>

<h3>Synchronous Clients<a class="headerlink" href="#synchronous-clients" title="Permalink to this headline">¶</a></h3>

<p>Of the client tags shown in the table, the following makes the <tt class="docutils literal"><span class="pre">basic_client</span></tt>

behave as a fully synchronous client.</p>

<li><strong>http_default_8bit_tcp_resolve</strong></li>

<li><strong>http_default_8bit_udp_resolve</strong></li>

<li><strong>http_keepalive_8bit_tcp_resolve</strong></li>

<li><strong>http_keepalive_8bit_udp_resolve</strong></li>

</ul>

</div></blockquote>

<p>The synchronous client implements all the operations of the client underneath

the interface all block to wait for I/O to finish. All the member methods are

synchronous and will block until the response object is ready or throws if erros

are encountered in the performance of the HTTP requests.</p>

<p class="first admonition-title">Warning</p>

<p class="last">The synchronous clients are <strong>NOT</strong> thread safe. You will need to do

external synchronization to use synchronous client implementations.</p>

</div>

<h3>Asynchronous Clients<a class="headerlink" href="#asynchronous-clients" title="Permalink to this headline">¶</a></h3>

<p>The following tags specify the <tt class="docutils literal"><span class="pre">basic_client</span></tt> to behave in an asynchronous

manner:</p>

<li><strong>http_async_8bit_tcp_resolve</strong></li>

<li><strong>http_async_8bit_udp_resolve</strong></li>

</ul>

</div></blockquote>

<p>An asynchronous client implementation means that``basic_client<...>`` is an

<a class="reference external" href="http://en.wikipedia.org/wiki/Active_object">Active Object</a>. This means that the client has and manages its own lifetime

thread, and returns values that are asynchronously filled in. The response

object encapsulates <a class="reference external" href="http://www.boost.org/libs/thread">Boost.Thread</a> futures which get filled in once the values

are available.</p>

<p>The asynchronous clients implement all operations asynchronously which are hidden

from the user. The interface is still synchronous but the fetching of data

happens on a different thread.</p>

<p class="last">The asynchronous clients are thread safe, and can be shared across

many threads. Each request starts a sequence of asynchronous operations

dedicated to that request. The client does not re-cycle connections and uses

a one-request-one-connection model.</p>

</div>

<h2>Member Functions<a class="headerlink" href="#member-functions" title="Permalink to this headline">¶</a></h2>

<p>In this section we assume that the following typedef is in effect:</p>

<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="o">::</span><span class="n">basic_client</span><span class="o"><</span>

<span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="o">::</span><span class="n">tags</span><span class="o">::</span><span class="n">http_default_8bit_udp_resolve</span>

<span class="n">client</span><span class="p">;</span>

</pre></div>

</div>

<p>Also, that code using the HTTP client will have use the following header:</p>

<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <boost/network/include/http/client.hpp></span>

</pre></div>

</div>

<p class="last">Starting version 0.9, cpp-netlib clients and server implementations

by default now have an externally-linked component. This is a breaking change

for code that used to rely on cpp-netlib being a header-only library, but can

inhibited by defining the <tt class="docutils literal"><span class="pre">BOOST_NETWORK_NO_LIB</span></tt> preprocessor macro before

including any cpp-netlib header.</p>

</div>

<h3>Constructors<a class="headerlink" href="#constructors" title="Permalink to this headline">¶</a></h3>

<p>The client implementation can be default constructed, or customized at

initialization.</p>

<dt><tt class="docutils literal"><span class="pre">client()</span></tt></dt>

<dd>Default constructor.</dd>

<dt><tt class="docutils literal"><span class="pre">client(boost::asio::io_service</span> <span class="pre">&</span> <span class="pre">io_service)</span></tt></dt>

<dd>Construct a client to use an existing Boost.Asio <tt class="docutils literal"><span class="pre">io_service</span></tt> instance.</dd>

<dt><tt class="docutils literal"><span class="pre">template</span> <span class="pre"><class</span> <span class="pre">ArgPack></span> <span class="pre">client(ArgPack</span> <span class="pre">const</span> <span class="pre">&</span> <span class="pre">args)</span></tt></dt>

<dd>Pass in an argument pack. See supported parameters in the table below.</dd>

</dl>

</colgroup>

<tr><th class="head">Parameter Name</th>

<th class="head">Description</th>

</tr>

</thead>

<tr><td>_follow_redirects</td>

<td>Boolean to specify

whether the client

should follow HTTP

redirects. Default is

<tt class="docutils literal"><span class="pre">false</span></tt>.</td>

</tr>

<tr><td>_cache_resolved</td>

<td>Boolean to specify

whether the client

should cache resolved

endpoints. The default

is <tt class="docutils literal"><span class="pre">false</span></tt>.</td>

</tr>

<tr><td>_io_service</td>

<td><tt class="docutils literal"><span class="pre">boost::asio::io_service</span> <span class="pre">&</span></tt></td>

<td>Reference to an

instance of a

Boost.Asio

<tt class="docutils literal"><span class="pre">io_service</span></tt>.</td>

</tr>

<tr><td>_openssl_certificate</td>

<td>string</td>

<td>The filename of the

certificate to load for

the SSL connection for

verification.</td>

</tr>

<tr><td>_openssl_verify_path</td>

<td>string</td>

<td>The directory from

which the certificate

authority files are

located.</td>

</tr>

</tbody>

</table>

<p>To use the above supported named parameters, you’ll have code that looks like

the following:</p>

<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="k">namespace</span> <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="p">;</span> <span class="c1">// parameters are in this namespace</span>

<span class="n">boost</span><span class="o">::</span><span class="n">asio</span><span class="o">::</span><span class="n">io_service</span> <span class="n">my_io_service</span><span class="p">;</span>

<span class="n">client</span> <span class="n">client_</span><span class="p">(</span><span class="n">_follow_redirects</span><span class="o">=</span><span class="kc">true</span><span class="p">,</span> <span class="n">_cache_resolved</span><span class="o">=</span><span class="kc">true</span><span class="p">,</span>

<span class="n">_io_service</span><span class="o">=</span><span class="n">my_io_service</span>

<span class="p">,</span> <span class="n">_openssl_certificate</span><span class="o">=</span><span class="s">"/tmp/my-cert"</span>

<span class="p">,</span> <span class="n">_openssl_verify_path</span><span class="o">=</span><span class="s">"/tmp/ca-certs/"</span><span class="p">);</span>

<span class="c1">// use client_ as normal from here on out.</span>

</pre></div>

</div>

<h3>HTTP Methods<a class="headerlink" href="#http-methods" title="Permalink to this headline">¶</a></h3>

<p>The client implementation supports various HTTP methods. The following

constructs assume that a client has been properly constructed named <tt class="docutils literal"><span class="pre">client_</span></tt>

and that there is an appropriately constructed request object named <tt class="docutils literal"><span class="pre">request_</span></tt>

and that there is an appropriately constructed response object named

<tt class="docutils literal"><span class="pre">response_</span></tt> like the following:</p>

<div class="highlight-c++"><div class="highlight"><pre><span class="n">client</span> <span class="n">client_</span><span class="p">();</span>

<span class="n">client</span><span class="o">::</span><span class="n">request</span> <span class="n">request_</span><span class="p">(</span><span class="s">"http://cpp-netib.github.com/"</span><span class="p">);</span>

<span class="n">client</span><span class="o">::</span><span class="n">response</span> <span class="n">response_</span><span class="p">;</span>

</pre></div>

</div>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.get(request_)</span></tt></dt>

<dd>Perform an HTTP GET request.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.head(request_)</span></tt></dt>

<dd>Perform an HTTP HEAD request.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.post(request_)</span></tt></dt>

<dd>Perform an HTTP POST, use the data already set in the request object which

includes the headers, and the body.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.post(request_,</span> <span class="pre">body)</span></tt></dt>

<dd>Body is a string of type <tt class="docutils literal"><span class="pre">boost::network::string<Tag>::type</span></tt> where <tt class="docutils literal"><span class="pre">Tag</span></tt>

is the HTTP Client’s <tt class="docutils literal"><span class="pre">Tag</span></tt>. The default content-type used is

<tt class="docutils literal"><span class="pre">x-application/octet-stream</span></tt>.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.post(request_,</span> <span class="pre">content_type,</span> <span class="pre">body)</span></tt></dt>

<dd>The body and content_type parameters are of type

<tt class="docutils literal"><span class="pre">boost::network::string<Tag>::type</span></tt> where <tt class="docutils literal"><span class="pre">Tag</span></tt> is the HTTP Client’s

<tt class="docutils literal"><span class="pre">Tag</span></tt>. This uses the request object’s other headers.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.put(request_)</span></tt></dt>

<dd>Perform an HTTP PUT, use the data already set in the request object which

includes the headers, and the body.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.put(request_,</span> <span class="pre">body)</span></tt></dt>

<dd>Body is a string of type <tt class="docutils literal"><span class="pre">boost::network::string<Tag>::type</span></tt> where <tt class="docutils literal"><span class="pre">Tag</span></tt>

is the HTTP Client’s <tt class="docutils literal"><span class="pre">Tag</span></tt>. The default content-type used is

<tt class="docutils literal"><span class="pre">x-application/octet-stream</span></tt>.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.put(request_,</span> <span class="pre">content_type,</span> <span class="pre">body)</span></tt></dt>

<dd>The body and content_type parameters are of type

<tt class="docutils literal"><span class="pre">boost::network::string<Tag>::type</span></tt> where <tt class="docutils literal"><span class="pre">Tag</span></tt> is the HTTP Client’s

<tt class="docutils literal"><span class="pre">Tag</span></tt>. This uses the request object’s other headers.</dd>

<dt><tt class="docutils literal"><span class="pre">response_</span> <span class="pre">=</span> <span class="pre">client_.delete_(request_)</span></tt></dt>

<dd>Perform an HTTP DELETE request.</dd>

</dl>

</div>

<h3>Client-Specific<a class="headerlink" href="#client-specific" title="Permalink to this headline">¶</a></h3>

<dt><tt class="docutils literal"><span class="pre">client_.clear_resolved_cache()</span></tt></dt>

<dd>Clear the cache of resolved endpoints.</dd>

</dl>

</div>

<h3><a href="index.html">Table Of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">HTTP Client API</a><ul>

<li><a class="reference internal" href="#general">General</a></li>

<li><a class="reference internal" href="#implementations">Implementations</a><ul>

<li><a class="reference internal" href="#synchronous-clients">Synchronous Clients</a></li>

<li><a class="reference internal" href="#asynchronous-clients">Asynchronous Clients</a></li>

</ul>

</li>

<li><a class="reference internal" href="#member-functions">Member Functions</a><ul>

<li><a class="reference internal" href="#constructors">Constructors</a></li>

<li><a class="reference internal" href="#http-methods">HTTP Methods</a></li>

<li><a class="reference internal" href="#client-specific">Client-Specific</a></li>

</ul>

</li>

</ul>

</li>

</ul>

<h3>Browse</h3>

<ul>

<li>Prev: <a href="reference.html">Reference Manual</a></li>

<li>Next: <a href="reference_http_request.html">HTTP Request</a></li>

</ul>

<ul>

<li>

<a href="index.html">cpp-netlib v0.9 documentation</a>

<ul><li><a href="reference.html">Reference Manual</a>

<ul><li>HTTP Client API</li></ul>

</li></ul>

</li>

</ul>

<li><a href="_sources/reference_http_client.txt"

rel="nofollow">Show Source</a></li>

</ul>

<h3>Quick search</h3>

</form>

Enter search terms or a module, class or function name.

</p>

</div>

</div>

« <a href="reference.html" title="Reference Manual">previous</a>

</div>

</div>

documentation automatically generated by <a href="http://sphinx.pocoo.org">Sphinx</a> | style mostly stolen from <a href="http://lettuce.it">lettuce.it</a>

| background image attributed to <a href="http://www.flickr.com/photos/OrangeSmell">OrangeSmell</a>

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

reference_http_client.html

Latest commit

History

reference_http_client.html

File metadata and controls