The C++ REST SDK (codename "Casablanca") has officially been released as an open source project on CodePlex (http://casablanca.codeplex.com).
We first announced Casablanca as an incubation project on Microsoft's DevLabs back in April of 2012. Since then we have had several releases and have seen library quickly evolve. As we added new features and received feedback from customers, it was evident that two separate entities were beginning to form. As a result, the "Casablanca" project on DevLabs has been separated into 2 different SDKs: the C++ REST SDK and the Azure SDK for C++.
The first of the two SDKs being released is the C++ REST SDK. It includes tools to quickly write modern, asynchronous C++ code that connects with REST services. We take advantage of the power and productivity offered in C++11 while providing a cross-platform solution. We currently support Windows 7, Windows 8 (Windows store and desktop applications), and Linux.
The main features in this SDK include:
- Ability to create a connection to a server via a HTTP Client, send requests and handle response.
- Support for construction and use of Uniform Resource Identifiers (URI).
- Constructing, parsing and serializing JSON values.
- Asynchronously reading/writing bytes to/from an underlying medium via Streams and Stream Buffers.
Let's look at some code to get a glimpse of the aforementioned features in action.
This first example is a simple application that uploads a file to an HTTP Server.
| #include #include #include usingnamespace concurrency::streams; usingnamespace web::http::client; usingnamespace web::http; void main() { // Open stream to file. file_stream<unsignedchar>::open_istream(L"myfile.txt").then([](basic_istream<unsignedchar> fileStream) { // Make HTTP request with the file stream as the body. uri serverUri(L"http://www.myhttpserver.com"); client.request(methods::PUT, L"myfile", fileStream).then([fileStream](http_response response) { fileStream.close(); // Perform actions here to inspect the HTTP response... if(response.status_code() == status_codes::OK) { } }); }); } |
We use the concurrency::streams::file_stream class to asynchronously read a file from disk. The constructor of the file stream returns a PPL task of a basic_istream.
Within the continuation we create an instance of http_client to represent the connection to the server. Using this instance we can now send requests. In this example we use the web::http::methods::PUT to specify the operation as an HTTP PUT request. We also include the name of the file and the file stream in our request. Finally, we capture the http_response in a continuation and perform the necessary actions to inspect if the request was successfully processed by the server.
This example illustrates how straight-forward writing a responsive client application that connects to a service can be.
Next we will demonstrate how to build a JSON value in memory and loop through its values.
#include void main() |
In the C++ REST SDK all JSON values are represented by the web::json::value class. In the example we build our JSON object using the value factory functions. A JSON value can also be parsed from a stream using a constructor that takes a stream reference. Once we have our JSON value we can use the cbegin and cend methods to return read-only iterators for the value collection.
Including this simple yet powerful representation of JSON objects in the SDK, provides developers with a set of tools that are productive and compose well together.
Thanks for taking the time to read this post, we hope that everyone gets a chance to visit the project on CodePlex, we would love to hear your feedback.
Stay tuned for more updates about both the C++ REST SDK and the Azure SDK for C++. A special thanks to Steve Gates for reviewing this post and providing the code snippets.