Http Client Tutorial

This tutorial walks through how to setup up a simple Windows desktop application utilizing Casablanca. In particular taking a look a look at how to use our http_client to connect to a server and download some data. Aside from the initial setup referencing up the NuGet package and Visual Studio specific photos, everything is NOT Windows specific. All the code and features described here work on any of our supported platforms.

Getting the C++ Rest SDK NuGet Package

The C++ Rest SDK NuGet package allows you to easily add Casablanca to an application without having to manually deal with setting up includes, libs, dlls, and deployment with Windows store applications. Make sure you have the Visual Studio NuGet Package Manager installed, the find the C++ Rest SDK NuGet package by right clicking on your project and selecting "Manage Nuget Packages...". From the dialog search for "Casablanca":



More detailed instruction for setting up our NuGet package can be located here.

Setting up Includes and Namespaces

Now that Casablanca is added to the project the next step is to include the header files we need. For this example we are going to use the http_client and one of Casablanca's asynchronous streams for files. To do so add the following includes:

#include "cpprest/http_client.h"
#include "cpprest/filestream.h"

Here is a list of other important header files in Casablanca, but we won't be using in this example:

#include "cpprest/http_listener.h"              // HTTP server
#include "cpprest/json.h"                       // JSON library
#include "cpprest/uri.h"                        // URI library
#include "cpprest/ws_client"                    // WebSocket client
#include "cpprest/containerstream.h"            // Async streams backed by STL containers
#include "cpprest/interopstream.h"              // Bridges for integrating Async streams with STL and WinRT streams
#include "cpprest/rawptrstream.h"               // Async streams backed by raw pointer to memory
#include "cpprest/producerconsumerstream.h"     // Async streams for producer consumer scenarios

To save explicitly typing common namespaces over and over add the following using statement:

using namespace utility;                    // Common utilities like string conversions
using namespace web;                        // Common features like URIs.
using namespace web::http;                  // Common HTTP functionality
using namespace web::http::client;          // HTTP client features
using namespace concurrency::streams;       // Asynchronous streams

Other important namespaces not used in this tutorial in Casablanca include:

using namespace web::http::experimental::listener;          // HTTP server
using namespace web::experimental::web_sockets::client;     // WebSockets client
using namespace web::json;                                  // JSON library

Making an Http Request and Saving the Results

In this tutorial we are going to asynchronously make a request to http://www.bing.com and save the results to a file. For this tutorial I'm creating a Windows console applications so all the code will be written inside the main() function, but it could be located in any function. First start by opening a stream to the file for us to save the response body in:

    auto fileStream = std::make_shared<ostream>();
    fstream::open_ostream(U("results.html")).then([=](ostream outFile)
    {
        *fileStream = outFile;
    })

So what is going on here is opening a raw byte stream to a file called results.html. Since this is a potentially blocking I/O operation it is being done asynchronously. The open_ostream function returns a PPL task. When the operation is completed the lambda specified to the continuation in the 'then' function will execute. More information about how to use PPL tasks can be located uri:here. Note here we are using a shared pointer to store the file stream to easily use across tasks.

Next lets create an http_client and make the actual Http request. Update the lambda to the following:

    fstream::open_ostream(U("results.html")).then([=](ostream outFile)
    {
        *fileStream = outFile;

        // Create http_client to send the request.
        http_client client(U("http://www.bing.com/"));

        // Build request URI and start the request.
        uri_builder builder(U("/search"));
        builder.append_query(U("q"), U("C++ Casablanca"));
        return client.request(methods::GET, builder.to_string());
    })

The code here is constructing and instance of Casablanca's http client for bing.com and then properly formulating the request query before sending the request. Now this lambda will return a task of the http response.