generic-library/msgpack
1
0
Fork 0
mirror of https://github.com/msgpack/msgpack-c.git synced 2025-05-01 23:31:03 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #407 from redboltz/add_doc

Browse Source 
Added unpack, pack, object, and object_handle documentation.
This commit is contained in:
Takatoshi Kondo 2016-01-19 09:06:58 +09:00
commit 6c035f7d2b
4 changed files with 925 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
include/msgpack/object.hpp
View File

@ -29,10 +29,17 @@ namespace msgpack {
MSGPACK_API_VERSION_NAMESPACE(v1) {
/// @endcond
/// The class holds object and zone
class object_handle {
public:
/// Constructor that creates nil object and null zone.
object_handle() {}
/// Constructor that creates an object_handle holding object `obj` and zone `z`.
/**
* @param obj object
* @param z zone
*/
object_handle(msgpack::object const& obj, msgpack::unique_ptr<msgpack::zone> z) :
m_obj(obj), m_zone(msgpack::move(z)) { }
@ -40,12 +47,24 @@ public:
void set(msgpack::object const& obj)
{ m_obj = obj; }
/// Get object reference
/**
* @return object
*/
const msgpack::object& get() const
{ return m_obj; }
/// Get unique_ptr reference of zone.
/**
* @return unique_ptr reference of zone
*/
msgpack::unique_ptr<msgpack::zone>& zone()
{ return m_zone; }
/// Get unique_ptr const reference of zone.
/**
* @return unique_ptr const reference of zone
*/
const msgpack::unique_ptr<msgpack::zone>& zone() const
{ return m_zone; }
@ -133,6 +152,14 @@ inline std::size_t aligned_zone_size(msgpack::object const& obj) {
return s;
}
/// clone object
/**
* Clone (deep copy) object.
* The copied object is located on newly allocated zone.
* @param obj copy source object
*
* @return object_handle that holds deep copied object and zone.
*/
inline object_handle clone(msgpack::object const& obj) {
std::size_t size = msgpack::aligned_zone_size(obj);
msgpack::unique_ptr<msgpack::zone> z(size == 0 ? nullptr : new msgpack::zone(size));

79
include/msgpack/object_fwd.hpp
View File

@ -99,7 +99,10 @@ public:
#endif // !defined(MSGPACK_USE_CPP03)
/// Object class that corresponding to MessagePack format object
/**
* See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
*/
struct object {
union union_type {
bool boolean;
@ -119,42 +122,114 @@ struct object {
msgpack::type::object_type type;
union_type via;
/// Cheking nil
/**
* @return If the object is nil, then return true, else return false.
*/
bool is_nil() const { return type == msgpack::type::NIL; }
#if defined(MSGPACK_USE_CPP03)
/// Get value as T
/**
* If the object can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type you want to get.
* @return The converted object.
*/
template <typename T>
T as() const;
#else // defined(MSGPACK_USE_CPP03)
/// Get value as T
/**
* If the object can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type you want to get.
* @return The converted object.
*/
template <typename T>
typename std::enable_if<msgpack::has_as<T>::value, T>::type as() const;
/// Get value as T
/**
* If the object can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type you want to get.
* @return The converted object.
*/
template <typename T>
typename std::enable_if<!msgpack::has_as<T>::value, T>::type as() const;
#endif // defined(MSGPACK_USE_CPP03)
/// Convert the object
/**
* If the object can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type of v.
* @param v The value you want to get. `v` is output parameter. `v` is overwritten by converted value from the object.
* @return The reference of `v`.
*/
template <typename T>
T& convert(T& v) const;
/// Convert the object (obsolete)
/**
* If the object can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type of v.
* @param v The pointer of the value you want to get. `v` is output parameter. `*v` is overwritten by converted value from the object.
* @return The pointer of `v`.
*/
template <typename T>
T* convert(T* v) const;
/// Convert the object if not nil
/**
* If the object is not nil and can't be converted to T, msgpack::type_error would be thrown.
* @tparam T The type of v.
* @param v The value you want to get. `v` is output parameter. `v` is overwritten by converted value from the object if the object is not nil.
* @return If the object is nil, then return false, else return true.
*/
template <typename T>
bool convert_if_not_nil(T& v) const;
/// Default constructor. The object is set to nil.
object();
/// Copy constructor. Object is shallow copied.
object(const msgpack_object& o);
/// Construct object from T
/**
* If `v` is the type that is corresponding to MessegePack format str, bin, ext, array, or map,
* you need to call `object(const T& v, msgpack::zone& z)` instead of this constructor.
*
* @tparam T The type of `v`.
* @param v The value you want to convert.
*/
template <typename T>
explicit object(const T& v);
/// Construct object from T
/**
* The object is constructed on the zone `z`.
* See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
*
* @tparam T The type of `v`.
* @param v The value you want to convert.
* @param z The zone that is used by the object.
*/
template <typename T>
object(const T& v, msgpack::zone& z);
// obsolete
/// Construct object from T (obsolete)
/**
* The object is constructed on the zone `z`.
* Use `object(const T& v, msgpack::zone& z)` instead of this constructor.
* See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
*
* @tparam T The type of `v`.
* @param v The value you want to convert.
* @param z The pointer to the zone that is used by the object.
*/
template <typename T>
object(const T& v, msgpack::zone* z);

517
include/msgpack/pack.hpp
View File

@ -26,68 +26,566 @@ namespace msgpack {
MSGPACK_API_VERSION_NAMESPACE(v1) {
/// @endcond
/// The class template that supports continuous packing.
/**
* @tparam Stream Any type that have a member function `Stream write(const char*, size_t s)`
*
*/
template <typename Stream>
class packer {
public:
/// Constructor
/**
* This constructor is left for compatibility.
* Use `packer(Stream* s)` instead of the constructor.
*
* @param s A pointer to packing destination stream object.
*/
packer(Stream* s);
/// Constructor
/**
* @param s Packing destination stream object.
*/
packer(Stream& s);
public:
/// Packing function template
/**
* @tparam T The type of packing object.
*
* @param v a packing object.
*
* @return The reference of `*this`.
*/
template <typename T>
packer<Stream>& pack(const T& v);
/// Packing uint8
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum or uint8.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_uint8(uint8_t d);
/// Packing uint16
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, uint8 or uint16.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_uint16(uint16_t d);
/// Packing uint32
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, uint8, uint16 or uint32.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_uint32(uint32_t d);
/// Packing uint16
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, uint8, uint16, uint32 or uint64.
* The minimum byte size expression is used.
* positive fixnum, uint8, uint16, or uint32 is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_uint64(uint64_t d);
/// Packing int8
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint8,
* else the packed type is negative fixnum, or int8
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_int8(int8_t d);
/// Packing int16
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, uint8, or uint16,
* else the packed type is negative fixnum, int8, or int16.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_int16(int16_t d);
/// Packing int32
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, uint8, uint16, or uint32,
* else the packed type is negative fixnum, int8, int16, or int32.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_int32(int32_t d);
/// Packing int32
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, uint8, uint16, uint32, or uint64,
* else the packed type is negative fixnum, int8, int16, int32, or int64.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_int64(int64_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always uint8.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_uint8(uint8_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always uint16.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_uint16(uint16_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always uint32.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_uint32(uint32_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always uint64.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_uint64(uint64_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always int8.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_int8(int8_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always int16.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_int16(int16_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always int32.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_int32(int32_t d);
/// Packing uint8 (fixed packed type).
/**
* The packed type is always int64.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_fix_int64(int64_t d);
/// Packing char
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_char(char d);
/// Packing signed char
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_signed_char(signed char d);
/// Packing short
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_short(short d);
/// Packing int
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_int(int d);
/// Packing long
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_long(long d);
/// Packing long long
/**
* The byte size of the packed data depends on `d`.
* If `d` is zero or positive, the packed type is positive fixnum, or uint*,
* else the packed type is negative fixnum, or int*
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_long_long(long long d);
/// Packing unsigned char
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, or uint*.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_unsigned_char(unsigned char d);
/// Packing unsigned short
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, or uint*.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_unsigned_short(unsigned short d);
/// Packing unsigned int
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, or uint*.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_unsigned_int(unsigned int d);
/// Packing unsigned long
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, or uint*.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_unsigned_long(unsigned long d);
/// Packing unsigned long long
/**
* The byte size of the packed data depends on `d`.
* The packed type is positive fixnum, or uint*.
* The minimum byte size expression is used.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-int
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_unsigned_long_long(unsigned long long d);
/// Packing float
/**
* The packed type is float32.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-float
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_float(float d);
/// Packing double
/**
* The packed type is float64.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-float
*
* @param d a packing object.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_double(double d);
/// Packing nil
/**
* The packed type is nil.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-nil
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_nil();
/// Packing true
/**
* The packed type is bool, value is true.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#bool-format-family
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_true();
/// Packing false
/**
* The packed type is bool, value is false.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#bool-format-family
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_false();
/// Packing array header and size
/**
* The packed type is array header and array size.
* You need to pack `n` msgpack objects following this header and size.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#array-format-family
*
* @param n The number of array elements (array size).
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_array(uint32_t n);
/// Packing map header and size
/**
* The packed type is map header and map size.
* You need to pack `n` pairs of msgpack objects following this header and size.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#map-format-family
*
* @param n The number of array elements (array size).
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_map(uint32_t n);
/// Packing str header and length
/**
* The packed type is str header and length.
* The minimum byte size length expression is used.
* You need to call `pack_str_body(const char* b, uint32_t l)` after this function calling with the same `l` value.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-str
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_str(uint32_t l);
/// Packing str body
/**
* You need to call this function just after `pack_str(uint32_t l)` calling.
* The value `l` should be the same as `pack_str(uint32_t l)` argument `l`.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-str
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_str_body(const char* b, uint32_t l);
// v4
/// Packing raw (v4) header and length
/**
* The packed type is raw header and length.
* The minimum byte size length expression is used.
* The format raw (v4) is old MessagePack version4 format.
* You need to call `pack_v4raw_body(const char* b, uint32_t l)` after this function calling with the same `l` value.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-str
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_v4raw(uint32_t l);
/// Packing raw (v4) body
/**
* The format raw (v4) is old MessagePack version4 format.
* You need to call this function just after `pack_v4raw(uint32_t l)` calling.
* The value `l` should be the same as `pack_v4raw(uint32_t l)` argument `l`.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-str
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_v4raw_body(const char* b, uint32_t l);
/// Packing bin header and length
/**
* The packed type is bin header and length.
* The minimum byte size length expression is used.
* You need to call `pack_bin_body(const char* b, uint32_t l)` after this function calling with the same `l` value.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_bin(uint32_t l);
/// Packing bin body
/**
* You need to call this function just after `pack_bin(uint32_t l)` calling.
* The value `l` should be the same as `pack_bin(uint32_t l)` argument `l`.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_bin_body(const char* b, uint32_t l);
/// Packing ext header, type, and length
/**
* The packed type is ext.
* The minimum byte size length expression is used.
* The length 1, 2, 4, 8, and 16 can be encoded in the header.
* You need to call `pack_ext_body(const char* b, uint32_t l)` after this function calling with the same `l` value.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#formats-ext
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_ext(size_t l, int8_t type);
/// Packing ext body
/**
* You need to call this function just after `pack_ext(size_t l, int8_t type)` calling.
* The value `l` should be the same as `pack_ext(size_t l, int8_t type)` argument `l`.
* See https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family
*
* @param l The length of string.
*
* @return The reference of `*this`.
*/
packer<Stream>& pack_ext_body(const char* b, uint32_t l);
private:
@ -128,12 +626,29 @@ public:
};
/// Pack the value as MessagePack format into the stream
/**
* This function template is left for compatibility.
* Use `void pack(Stream& s, const T& v)` instead of the function template.
*
* @tparam Stream Any type that have a member function `Stream write(const char*, size_t s)`
* @tparam T Any type that is adapted to MessagePack
* @param s The pointer to packing destination stream
* @param v Packing value
*/
template <typename Stream, typename T>
inline void pack(Stream* s, const T& v)
{
packer<Stream>(*s).pack(v);
}
/// Pack the value as MessagePack format into the stream
/**
* @tparam Stream Any type that have a member function `Stream write(const char*, size_t s)`
* @tparam T Any type that is adapted to MessagePack
* @param s Packing destination stream
* @param v Packing value
*/
template <typename Stream, typename T>
inline void pack(Stream& s, const T& v)
{

356
include/msgpack/unpack.hpp
View File

@ -60,7 +60,18 @@ namespace msgpack {
MSGPACK_API_VERSION_NAMESPACE(v1) {
/// @endcond
typedef bool (*unpack_reference_func)(msgpack::type::object_type, std::size_t, void*);
/// The type of reference or copy judging function.
/**
* @param type msgpack data type.
* @param size msgpack data size.
* @param user_data The user_data that is set by msgpack::unpack functions.
*
* @return If the data should be referenced, then return true, otherwise (should be copied) false.
*
* This function is called when unpacking STR, BIN, or EXT.
*
*/
typedef bool (*unpack_reference_func)(msgpack::type::object_type type, std::size_t size, void* user_data);
struct unpack_error : public std::runtime_error {
explicit unpack_error(const std::string& msg)
@ -985,11 +996,21 @@ inline int context::execute(const char* data, std::size_t len, std::size_t& off)
typedef object_handle unpacked;
/// Unpacking class for a stream deserialization.
class unpacker {
public:
/// Constructor
/**
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param initial_buffer_size The memory size to allocate when unpacker is constructed.
* @param limit The size limit information of msgpack::object.
*
*/
unpacker(unpack_reference_func f = &unpacker::default_reference_func,
void* user_data = nullptr,
std::size_t init_buffer_size = MSGPACK_UNPACKER_INIT_BUFFER_SIZE,
std::size_t initial_buffer_size = MSGPACK_UNPACKER_INIT_BUFFER_SIZE,
unpack_limit const& limit = unpack_limit());
#if !defined(MSGPACK_USE_CPP03)
@ -1000,60 +1021,97 @@ public:
~unpacker();
public:
/*! 1. reserve buffer. at least `size' bytes of capacity will be ready */
/// Reserve a buffer memory.
/**
* @param size The size of allocating memory.
*
* After returning this function, buffer_capacity() returns at least 'size'.
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
void reserve_buffer(std::size_t size = MSGPACK_UNPACKER_RESERVE_SIZE);
/*! 2. read data to the buffer() up to buffer_capacity() bytes */
/// Get buffer pointer.
/**
* You need to care about the memory is enable between buffer() and buffer() + buffer_capacity()
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
char* buffer();
/// Get buffer capacity.
/**
* @return The memory size that you can write.
*
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
std::size_t buffer_capacity() const;
/*! 3. specify the number of bytes actually copied */
/// Notify a buffer consumed information to msgpack::unpacker.
/**
* @param size The size of memory that you consumed.
*
* After copying the data to the memory that is pointed by buffer(), you need to call the
* function to notify how many bytes are consumed. Then you can call next() functions.
*
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
void buffer_consumed(std::size_t size);
/*! 4. repeat next() until it retunrs false */
/// Unpack one msgpack::object. [obsolete]
/**
*
* @param result The object that contains unpacked data.
*
* @return If one msgpack::object is unpacked, then return true, if msgpack::object is incomplete
* and additional data is required, then return false. If data format is invalid, throw
* msgpack::parse_error.
*
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
* This function is obsolete. Use the reference inteface version of next() function instead of
* the pointer interface version.
*/
bool next(unpacked* result);
/// Unpack one msgpack::object.
/**
*
* @param result The object that contains unpacked data.
* @param referenced If the unpacked object contains reference of the buffer,
* then set as true, otherwise false.
*
* @return If one msgpack::object is unpacked, then return true, if msgpack::object is incomplete
* and additional data is required, then return false. If data format is invalid, throw
* msgpack::parse_error.
*
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
bool next(unpacked& result, bool& referenced);
/// Unpack one msgpack::object.
/**
*
* @param result The object that contains unpacked data.
*
* @return If one msgpack::object is unpacked, then return true, if msgpack::object is incomplete
* and additional data is required, then return false. If data format is invalid, throw
* msgpack::parse_error.
*
* See:
* https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_unpacker#msgpack-controls-a-buffer
*/
bool next(unpacked& result);
/*! 5. check if the size of message doesn't exceed assumption. */
/// Get message size.
/**
* @return Returns parsed_size() + nonparsed_size()
*/
std::size_t message_size() const;
// Basic usage of the unpacker is as following:
//
// unpacker pac;
// while( /* input is readable */ ) {
//
// // 1.
// pac.reserve_buffer(32*1024);
//
// // 2.
// std::size_t bytes = input.readsome(pac.buffer(), pac.buffer_capacity());
//
// // error handling ...
//
// // 3.
// pac.buffer_consumed(bytes);
//
// // 4.
// unpacked result;
// while(pac.next(&result)) {
// // do some with the object with the zone.
// object obj = result.get();
// std::auto_ptr<msgpack:zone> z = result.zone();
// on_message(obj, z);
//
// //// boost::shared_ptr is also usable:
// // boost::shared_ptr<zone> life(z.release());
// // on_message(result.get(), life);
// }
//
// // 5.
// if(pac.message_size() > 10*1024*1024) {
// throw std::runtime_error("message is too large");
// }
// }
//
/*! for backward compatibility */
bool execute();
@ -1070,20 +1128,48 @@ public:
void reset();
public:
// These functions are usable when non-MessagePack message follows after
// MessagePack message.
/// Get parsed message size.
/**
* @return Parsed message size.
*
* This function is usable when non-MessagePack message follows after
* MessagePack message.
*/
std::size_t parsed_size() const;
/*! get address of the buffer that is not parsed */
/// Get the address that is not parsed in the buffer.
/**
* @return Address of the buffer that is not parsed
*
* This function is usable when non-MessagePack message follows after
* MessagePack message.
*/
char* nonparsed_buffer();
/// Get the size of the buffer that is not parsed.
/**
* @return Size of the buffer that is not parsed
*
* This function is usable when non-MessagePack message follows after
* MessagePack message.
*/
std::size_t nonparsed_size() const;
/*! skip specified size of non-parsed buffer, leaving the buffer */
// Note that the `size' argument must be smaller than nonparsed_size()
/// Skip the specified size of non-parsed buffer.
/**
* @param size to skip
*
* Note that the `size' argument must be smaller than nonparsed_size().
* This function is usable when non-MessagePack message follows after
* MessagePack message.
*/
void skip_nonparsed_buffer(std::size_t size);
/*! remove unparsed buffer from unpacker */
// Note that reset() leaves non-parsed buffer.
/// Remove nonparsed buffer and reset the current position as a new start point.
/**
* This function is usable when non-MessagePack message follows after
* MessagePack message.
*/
void remove_nonparsed_buffer();
private:
@ -1112,57 +1198,213 @@ private:
#endif // defined(MSGPACK_USE_CPP03)
};
/// Unpack msgpack::object from a buffer.
/**
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return unpacked object that contains unpacked data.
*
*/
unpacked unpack(
const char* data, std::size_t len, std::size_t& off, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return unpacked object that contains unpacked data.
*
*/
unpacked unpack(
const char* data, std::size_t len, std::size_t& off,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return unpacked object that contains unpacked data.
*
*/
unpacked unpack(
const char* data, std::size_t len, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return unpacked object that contains unpacked data.
*
*/
unpacked unpack(
const char* data, std::size_t len,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param result The object that contains unpacked data.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
*
*/
void unpack(unpacked& result,
const char* data, std::size_t len, std::size_t& off, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param result The object that contains unpacked data.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
*
*/
void unpack(unpacked& result,
const char* data, std::size_t len, std::size_t& off,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param result The object that contains unpacked data.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
*
*/
void unpack(unpacked& result,
const char* data, std::size_t len, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param result The object that contains unpacked data.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
*
*/
void unpack(unpacked& result,
const char* data, std::size_t len,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param z The msgpack::zone that is used as a memory of unpacked msgpack objects.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return msgpack::object that contains unpacked data.
*
*/
msgpack::object unpack(
msgpack::zone& z,
const char* data, std::size_t len, std::size_t& off, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param z The msgpack::zone that is used as a memory of unpacked msgpack objects.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return msgpack::object that contains unpacked data.
*
*/
msgpack::object unpack(
msgpack::zone& z,
const char* data, std::size_t len, std::size_t& off,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param z The msgpack::zone that is used as a memory of unpacked msgpack objects.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return msgpack::object that contains unpacked data.
*
*/
msgpack::object unpack(
msgpack::zone& z,
const char* data, std::size_t len, bool& referenced,
unpack_reference_func f = nullptr, void* user_data = nullptr,
unpack_limit const& limit = unpack_limit());
/// Unpack msgpack::object from a buffer.
/**
* @param z The msgpack::zone that is used as a memory of unpacked msgpack objects.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* @return msgpack::object that contains unpacked data.
*
*/
msgpack::object unpack(
msgpack::zone& z,
const char* data, std::size_t len,
@ -1170,7 +1412,19 @@ msgpack::object unpack(
unpack_limit const& limit = unpack_limit());
// obsolete
/// Unpack msgpack::object from a buffer. [obsolete]
/**
* @param result The object that contains unpacked data.
* @param data The pointer to the buffer.
* @param len The length of the buffer.
* @param off The offset position of the buffer. It is read and overwritten.
* @param referenced If the unpacked object contains reference of the buffer, then set as true, otherwise false.
* @param f A judging function that msgpack::object refer to the buffer.
* @param user_data This parameter is passed to f.
* @param limit The size limit information of msgpack::object.
*
* This function is obsolete. Use the reference inteface version of unpack functions instead of the pointer interface version.
*/
void unpack(unpacked* result,
const char* data, std::size_t len, std::size_t* off = nullptr, bool* referenced = nullptr,
unpack_reference_func f = nullptr, void* user_data = nullptr,