简介
c++REST SDK，又叫卡萨布兰卡是一个微软发布的C++基于云的客户机-服务器通信库。该库基于现代化的C++异步API，即Promise模型或叫链式异步模型设计[1]，c++开发人员可以方便地连接并与服务交互。
SDK内容
- 特性——HTTP客户机/服务器，JSON，URI，异步流，WebSockets客户机,oAuth
- PPL任务[2] ——一个强大的基于c++11特性编写的异步操作模型
- 支持平台——Windows桌面，Windows Store，Windows Phone，Ubuntu，OS X，iOS和Android
- Windows平台编译支持——VS 2012，2013年和2015
- 非Windows平台编译支持——cmake
- 包管理器支持——NuGet，仅在VS编译器支持Windows和Android平台[3]
Http Client示例
#include
#include
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
int main(int argc, char* argv[])
{
auto fileStream = std::make_shared();
// Open stream to output file.
pplx::task requestTask = 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("cpprestsdk github"));
return client.request(methods::GET, builder.to_string());
})
// Handle response headers arriving.
.then([=](http_response response)
{
printf("Received response status code:%u\n", response.status_code());
// Write response body into the file.
return response.body().read_to_end(fileStream->streambuf());
})
// Close the file stream.
.then([=](size_t)
{
return fileStream->close();
});
// Wait for all the outstanding I/O to complete and handle any exceptions
try
{
requestTask.wait();
}
catch (const std::exception &e)
{
printf("Error exception:%s\n", e.what());
}
return 0;
}
JSON
构造JSON
JSON是JavaScript Object Notation，也就是JS对象表示法的简称。由于它的简单，紧凑，灵活，占用空间小，与JS无缝衔接等优点，近年来已经替代xml成为web通信的主要信息载体。在cpprest中，JSON值是由web::json::value类来表示的，不管它是一个数值，一个字符串，或者一个对象，它都可以是一个JSON值。正是由于JSON可以表示任何静态数据类型，所以有不少语言有不少库支持JSON对象和编程语言对象的直接映射，但这些库在提高编码效率的同时，也都有或多或少的问题，有的有性能问题，有的对代码有侵入性，如必须继承某一基类，需要谨慎选用。
构建一个JSON值，最简单的方式，我们可以通过使用普通的c++值来构建。cpprest提供了一个重载的工厂函数，该函数可以构建6种类型的JSON值，示例如下：
using namespace web;
...
json::value v0 = json::value::null();
json::value v1 = json::value::number(17);
json::value v2 = json::value::number(3.1415);
json::value v3 = json::value::boolean(true);
json::value v4 = json::value::string(U("Hello Again!"));
json::value v5 = json::value::object();
json::value v6 = json::value::array();
解析和序列化
对于JSON来说，几乎所有实际中的使用，都是将类型转化成JSON或从JSON转化成相应的类型，所以一个常见的构建JSON的方式，就是通过解析。
我们可以通过解析的方法从一个流或字符串中生成一个JSON，如：
using namespace web;
...
utility::stringstream_t ss1;
ss1 << U("17");
json::value v1 = json::value::parse(ss1);
相反的方向也同样简单:
using namespace web;
...
utility::stringstream_t stream;
json::value v1 = json::value::string(U("Hi"));
v1.serialize(stream);
访问数据
除了添加元素，添加字段和写JSON值到一个流中，对一个JSON来说，没太多操作可做：因为JSON并不是用于作为一个通用的动态数值系统来设计的，他的主要作用就是对JSON对象做读写操作。对于一个的值处理，还是应该仰仗于C++系统，所以我们就需要一种从JSON对象得到C++值的方法。cpprest强迫我们从JSON中取值时，通过使用"as_xxx()"这样的函数来明确指定C++类型，而不是提供隐式转换操作，如：
int i = v1.as_integer();
double d = v2.as_double();
bool b = v3.as_bool();
utility::string_t s = v4.as_string();
如果JSON内部数据跟我们要求的类型不一致时，转换将抛出一个类型为json::json_exception的异常。如，当要求转换一个字符串到double或布尔时，就发生失败。访问JSON数组的单个或对象类型的成员变量有几种方式。其中一种方法就是使用[]函数，下标操作符是非“常量”的操作，并且可以修改JSON值，在必要时，会添加一个null值。
json::value obj = json::value::parse(U("{ \"a\" : 10 }"));
obj[U("a")] = json::value(12);
obj[U("b")] = json::value(13);
auto nullValue = obj[U("c")];
在上面的代码中，字符串"a"的值，将从10变为12，将在obj中添加一个"b"，其值为13，由于obj中没有"c"，直接读取"c"时，将会返回一个null值。
通过不插入任何职方式访问JSON数组和对象时，可以使用json::value::at方法。如果值存在，则该方法就返回一个JSON值得引用，如果不存在，则抛出一个json::json_exeption异常。
json::value obj = json::value::parse(U("{ \"a\" : 10 }"));
auto aValue = obj.at(U("a"));
auto bValue = obj.at(U("b"));
在上面的代码中，调用"at"方法，访问"a"，将返回一个JSON数值10，而访问"b"将抛出异常。我们可以通过json::value::size()和json::value::has_field来检测大小和一个JSON字段是否存在。
相比于其他类型，数值型操作，会多一个动作，指定具体是哪种类型的数值，如：
json::value num = json::value(88);
int64_t num64 = num.as_number().to_int64();
WebSocket客户端
关于websocekts所有相关的东西都在头文件:ws_client.h，命名空间：web::web sockets::client。
#include
using namespace web;
using namespace web::websockets::client;
类 websocket_client被用来创建 和维持一个到WebSocket端点的连接。一旦你有你的客户端，你就必须使用函数'connect()'连接到一个远端,并且传入一个该客户端要连接的URI，该函数会返回一个可以等待的pplx::task。
websocket_client client;
client.connect(U("ws://localhost:1234")).then([](){ /* We've finished connecting. */ });
一旦客户端连接上，你就可以开始发送和接受数据。就跟C++ Rest SDK的rest部分一样，这是一异步的方式完成的。
websocket_outgoing_message msg;
msg.set_utf8_message("I am a UTF-8 string! (Or close enough...)");
client.send(msg).then([](){ /* Successfully sent the message. */ });
client.receive().then([](websocket_incoming_message msg) {
return msg.extract_string();
}).then([](std::string body) {
std::cout << body << std::endl;
});
(注意：每来一条消息，只有一个'receive()'函数会被调用)
我们支持发送和接收字符串和二进制消息。
websocket_outgoing_message msg;
concurrency::streams::producer_consumer_buffer buf;
std::vector body(6);
memcpy(&body[0], "a\0b\0c\0", 6);
auto send_task = buf.putn(&body[0], body.size()).then([&](size_t length) {
msg.set_binary_message(buf.create_istream(), length);
return client.send(msg);
}).then([](pplx::task t)
{
try
{
t.get();
}
catch(const websocket_exception& ex)
{
std::cout << ex.what();
}
});
send_task.wait();
一旦结束，我们就应该关闭它。
client.close().then([](){ /* Successfully closed the connection. */ });
有时甚至是大部分时候你从服务端接收许多消息，需要不断地调用websocket_client::receive()并处理每个任务，肯定是很繁琐而且易错的，这时我们有另一个类websocket_callback_client，它允许设置一个回调函数来接收从服务器发来的消息。注册回调函数的实例如下：
websocket_callback_client client;
client.connect(U("ws://localhost:1234")).then([](){ /* We've finished connecting. */ });
// set receive handler
client.set_message_handler([](websocket_incoming_message msg)
{
// handle message from server...
});
-
微软把它称作基于任务的异步编程 ↩
-
PPL，全称为Parallel Patterns Library，并行模式库，在cpprest中改名为pptx，为了与ppl共存(ppl默认存在于VS2012以上版本中) ↩
-
部分语言包管理器：1 苹果的XCode支持CocoaPods管理器，同时支持Objective C和Swift开发OS X和iOS应用。 2 Java分别有ant(在主流项目开发中，基本弃用)，maven(用xml管理第三方库)和gradle(用基于Groovy的动态DSL管理第三方库) ↩