diff --git a/QUICKSTART-C.md b/QUICKSTART-C.md new file mode 100644 index 00000000..97d3bdf1 --- /dev/null +++ b/QUICKSTART-C.md @@ -0,0 +1,194 @@ +# Implementation Status + +The serialization library is production-ready. + +Currently, no RPC implementation is not available. + +# Install + + +## Mac OS X with MacPorts + +On Mac OS X, you can install MessagePack for C using MacPorts. + +``` +$ sudo port install msgpack +``` + +You might need to run `sudo port selfupdate` before installing to update the package repository. + +You can also install via Homebrew. + +``` +$ sudo brew install msgpack +``` + +## FreeBSD with Ports Collection + +On FreeBSD, you can use Ports Collection. Install [net/msgpack|http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/msgpack/] package. + +## Gentoo Linux with Portage + +On Gentoo Linux, you can use emerge. Install [dev-libs/msgpack|http://gentoo-portage.com/dev-libs/msgpack] package. + +## Other UNIX-like platform with ./configure + +On the other UNIX-like platforms, download source package from [Releases|http://msgpack.org/releases/cpp/] and run `./configure && make && make install`. + +``` +$ wget http://msgpack.org/releases/cpp/msgpack-0.5.5.tar.gz +$ tar zxvf msgpack-0.5.5.tar.gz +$ cd msgpack-0.5.5 +$ ./configure +$ make +$ sudo make install +``` + +## Windows + +On Windows, download source package from [here|https://sourceforge.net/projects/msgpack/files/] and extract it. +Then open `msgpack_vc8.vcproj` file and build it using batch build. It builds libraries on `lib/` folder and header files on `include/` folder. + +You can build using command line as follows: + +``` +> vcbuild msgpack_vc2008.vcproj +> dir lib % DLL files are here +> dir include % header files are here +``` + +## Install from git repository + +You need to install gcc (4.1.0 or higher), autotools. + +``` +$ git clone git@github.com:msgpack/msgpack.git +$ cd msgpack/cpp +$ ./bootstrap +$ ./configure +$ make +$ sudo make install +``` + +# Serialization QuickStart for C + +## First program + +Include `msgpack.h` header and link `msgpack` library to use MessagePack on your program. + +```c +#include +#include + +int main(void) { + + /* creates buffer and serializer instance. */ + msgpack_sbuffer* buffer = msgpack_sbuffer_new(); + msgpack_packer* pk = msgpack_packer_new(buffer, msgpack_sbuffer_write); + + /* serializes ["Hello", "MessagePack"]. */ + msgpack_pack_array(pk, 2); + msgpack_pack_raw(pk, 5); + msgpack_pack_raw_body(pk, "Hello", 5); + msgpack_pack_raw(pk, 11); + msgpack_pack_raw_body(pk, "MessagePack", 11); + + /* deserializes it. */ + msgpack_unpacked msg; + msgpack_unpacked_init(&msg); + bool success = msgpack_unpack_next(&msg, buffer->data, buffer->size, NULL); + + /* prints the deserialized object. */ + msgpack_object obj = msg.data; + msgpack_object_print(stdout, obj); /*=> ["Hello", "MessagePack"] */ + + /* cleaning */ + msgpack_sbuffer_free(buffer); + msgpack_packer_free(pk); +} +``` + +## Simple program with a loop + +```c +#include +#include + +int main(void) { + + /* creates buffer and serializer instance. */ + msgpack_sbuffer* buffer = msgpack_sbuffer_new(); + msgpack_packer* pk = msgpack_packer_new(buffer, msgpack_sbuffer_write); + + int j; + + for(j = 0; j<23; j++) { + /* NB: the buffer needs to be cleared on each iteration */ + msgpack_sbuffer_clear(buffer); + + /* serializes ["Hello", "MessagePack"]. */ + msgpack_pack_array(pk, 3); + msgpack_pack_raw(pk, 5); + msgpack_pack_raw_body(pk, "Hello", 5); + msgpack_pack_raw(pk, 11); + msgpack_pack_raw_body(pk, "MessagePack", 11); + msgpack_pack_int(pk, j); + + /* deserializes it. */ + msgpack_unpacked msg; + msgpack_unpacked_init(&msg); + bool success = msgpack_unpack_next(&msg, buffer->data, buffer->size, NULL); + + /* prints the deserialized object. */ + msgpack_object obj = msg.data; + msgpack_object_print(stdout, obj); /*=> ["Hello", "MessagePack"] */ + puts(""); + } + + /* cleaning */ + msgpack_sbuffer_free(buffer); + msgpack_packer_free(pk); +} +``` + +## Streaming feature + +```c +#include +#include + +int main(void) { + /* serializes multiple objects using msgpack_packer. */ + msgpack_sbuffer* buffer = msgpack_sbuffer_new(); + msgpack_packer* pk = msgpack_packer_new(buffer, msgpack_sbuffer_write); + msgpack_pack_int(pk, 1); + msgpack_pack_int(pk, 2); + msgpack_pack_int(pk, 3); + + /* deserializes these objects using msgpack_unpacker. */ + msgpack_unpacker pac; + msgpack_unpacker_init(&pac, MSGPACK_UNPACKER_INIT_BUFFER_SIZE); + + /* feeds the buffer. */ + msgpack_unpacker_reserve_buffer(&pac, buffer->size); + memcpy(msgpack_unpacker_buffer(&pac), buffer->data, buffer->size); + msgpack_unpacker_buffer_consumed(&pac, buffer->size); + + /* now starts streaming deserialization. */ + msgpack_unpacked result; + msgpack_unpacked_init(&result); + + while(msgpack_unpacker_next(&pac, &result)) { + msgpack_object_print(stdout, result.data); + puts(""); + } + + /* results: + * $ gcc stream.cc -lmsgpack -o stream + * $ ./stream + * 1 + * 2 + * 3 + */ +} +``` diff --git a/QUICKSTART-CPP.md b/QUICKSTART-CPP.md new file mode 100644 index 00000000..6350c559 --- /dev/null +++ b/QUICKSTART-CPP.md @@ -0,0 +1,159 @@ +# Implementation Status + +The serialization library is production-ready. + +Currently, RPC implementation is testing phase. Requires newer kernel, not running on RHEL5/CentOS5. + +# Install + +Same as QuickStart for C Language. + +# Serialization QuickStart for C+\+ + +## First program + +Include `msgpack.hpp` header and link `msgpack` library to use MessagePack on your program. + +```cpp +#include +#include +#include +#include + +int main(void) { + // serializes this object. + std::vector vec; + vec.push_back("Hello"); + vec.push_back("MessagePack"); + + // serialize it into simple buffer. + msgpack::sbuffer sbuf; + msgpack::pack(sbuf, vec); + + // deserialize it. + msgpack::unpacked msg; + msgpack::unpack(&msg, sbuf.data(), sbuf.size()); + + // print the deserialized object. + msgpack::object obj = msg.get(); + std::cout << obj << std::endl; //=> ["Hello", "MessagePack"] + + // convert it into statically typed object. + std::vector rvec; + obj.convert(&rvec); +} +``` + +Compile it as follows: + +``` +$ g++ hello.cc -lmsgpack -o hello +$ ./hello +["Hello", "MessagePack"] +``` + +## Streaming feature + +```cpp +#include +#include +#include + +int main(void) { + // serializes multiple objects using msgpack::packer. + msgpack::sbuffer buffer; + + msgpack::packer pk(&buffer); + pk.pack(std::string("Log message ... 1")); + pk.pack(std::string("Log message ... 2")); + pk.pack(std::string("Log message ... 3")); + + // deserializes these objects using msgpack::unpacker. + msgpack::unpacker pac; + + // feeds the buffer. + pac.reserve_buffer(buffer.size()); + memcpy(pac.buffer(), buffer.data(), buffer.size()); + pac.buffer_consumed(buffer.size()); + + // now starts streaming deserialization. + msgpack::unpacked result; + while(pac.next(&result)) { + std::cout << result.get() << std::endl; + } + + // results: + // $ g++ stream.cc -lmsgpack -o stream + // $ ./stream + // "Log message ... 1" + // "Log message ... 2" + // "Log message ... 3" +} +``` + +### Streaming into an array or map + +```cpp +#include +#include +#include + +int main(void) { + // serializes multiple objects into one message containing an array using msgpack::packer. + msgpack::sbuffer buffer; + + msgpack::packer pk(&buffer); + pk.pack_array(3) + pk.pack(std::string("Log message ... 1")); + pk.pack(std::string("Log message ... 2")); + pk.pack(std::string("Log message ... 3")); + + // serializes multiple objects into one message containing a map using msgpack::packer. + msgpack::sbuffer buffer2; + + msgpack::packer pk2(&buffer2); + pk2.pack_map(2) + pk2.pack(std::string("x")); + pk2.pack(3); + pk2.pack(std::string("y)); + pk2.pack(3.4321); + +} +``` + + +## User-defined classes + +You can use serialize/deserializes user-defined classes using MSGPACK_DEFINE macro. + +```cpp +#include +#include +#include + +class myclass { +private: + std::string m_str; + std::vector m_vec; +public: + MSGPACK_DEFINE(m_str, m_vec); +}; + +int main(void) { + std::vector vec; + // add some elements into vec... + + // you can serialize myclass directly + msgpack::sbuffer sbuf; + msgpack::pack(sbuf, vec); + + msgpack::unpacked msg; + msgpack::unpack(&msg, sbuf.data(), sbuf.size()); + + msgpack::object obj = msg.get(); + + // you can convert object to myclass directly + std::vector rvec; + obj.convert(&rvec); +} +```