/** Copyright 2007-2014 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com* John Scipione, jscipione@gmail.com** Corresponds to:* headers/os/support/Flattenable.h rev 39675* src/kits/support/Flattenable.cpp rev 12963*//*!\file Flattenable.h\ingroup support\ingroup libbe\brief Provides the BFlattenable interface*//*!\class BFlattenable\ingroup support\ingroup libbe\brief Interface for classes that can flatten and unflatten themselves toa stream of bytes.It is convenient that objects can be stored as a flat stream of bytes. Inthis way, they can be written to disk, exchanged between applications or sendover networks. This ability, known as marshaling in many other programminglanguages, is not native to C++. The Haiku API has created a universalinterface that classes have if they are able to be flattened. Thisclass defines the interface. This class does nothing on its own, andtherefore contains pure virtual functions. By inheriting this class andimplementing the methods in your own class, you will be able to use yourobjects as flattenable objects throughout the Haiku API.Flattened objects can be used for example when sending messages within anapplication or between applications. The BMessage class uses the interfaceto store and transmit custom classes.If you want to be able to flatten your objects, you will need to implementvarious methods. Flatten() and Unflatten() are where the magic happen. Thesemethods handle the actual flattening and unflattening. To identify flatteneddata in for example BMessage, the object has a type_code. Type codes arefour byte long integers. You can choose to flatten to one of the existingtypes, if you are certain that you are compatible to those, but you'llusually define your own type. Your best option is by using a multicharacterconstant, such as 'STRI'. Implement TypeCode() to return the type yousupport. Implement FlattenedSize() to make sure that other objects canprovide the right buffers. Implement IsFixedSize() to return whether yourobjects always store to a fixed size.See the following example:\codetype_code CUSTOM_STRING_TYPE = 'CUST';class CustomString : public BFlattenable {public:char data[100];// from BFlattenablebool IsFixedSize() const { return false; };type_code TypeCode() const { return CUSTOM_STRING_TYPE; };ssize_t FlattenedSize() const { return strlen(data); };status_t Flatten(void* buffer, ssize_t size) const{if ((strlen(data) + 1) < size)return B_BAD_VALUE;memcpy(buffer, data, size);return B_OK;};status_t Unflatten(type_code code, const void* buffer, ssize_t size){if (code != CUSTOM_STRING_TYPE)return B_BAD_TYPE;if (size > 100)return B_NO_MEMORY;memcpy(data, buffer, size);return B_OK;};};\endcodeHave a look at TypeConstants.h for a list of all the types that the HaikuAPI defines.The Haiku API has a second interface for storing objects, which is withBArchivable. BArchivable is for more complex cases. Instead of one flatdatastream, it stores an object in a BMessage. In that way you can reflectinternals of a class better. It also provides an interface for instantiatingobjects, that is, for objects to restore themselves from a BMessage. Inessence, BArchivable is more suitable for objects that are alive. In shortBFlattenable is for data objects, BArchivable is for 'live' objects.Other classes in the API that support flattening and unflattening are forexample BMessage, which enables you to conveniently write flattened datato disk. Another example is BPath. Because of that you can store paths andsend them over via messages. Throughout the Haiku API you will find classesthat provide the flattening interface.\since BeOS R3*//*!\fn virtual bool BFlattenable::IsFixedSize() const\brief Pure virtual that should return whether or not flattened objects ofthis type always have a fixed size.\return Should return whether or not the flattened objects of this typealways have a fixed size.\since BeOS R3*//*!\fn virtual type_code BFlattenable::TypeCode() const\brief Pure virtual that returns the type_code this class flattens to.\return Either one of the existing typecodes found in TypeConstants.hif your class actually is compatible to those formats, or acustom four-byte integer constant if not.\since BeOS R3*//*!\fn virtual ssize_t BFlattenable::FlattenedSize() const\brief Pure virtual that should return the size of the flattened object inbytes.\since BeOS R3*//*!\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const\brief Pure virtual that should flatten the object into the supplied\a buffer.Please make sure that you check that the supplied buffer is not a \c NULLpointer. Also make sure that the size of the flattened object does isn'tlarger than the size of the buffer.\param buffer The buffer to flatten in.\param size The size of the buffer.\retval B_OK The object was flattened.\retval B_NO_MEMORY The buffer was smaller than required.\retval B_BAD_VALUE The buffer was a \c NULL pointer.\since BeOS R3*//*!\fn bool BFlattenable::AllowsTypeCode(type_code code) const\brief Get whether or not the supplied type_code is supported.This default implementation checks the \a code argument against the type_codereturned by TypeCode().\param code The type_code constant you want to check for.\returns Whether or not the supplied type_code is supported.\retval true The type_code is supported.\retval false The type_code is not supported.\since BeOS R3*//*!\fn virtual status_t BFlattenable::Unflatten(type_code code,const void* buffer, ssize_t size)\brief Pure virtual that should unflatten the buffer and put the contentsinto the current object.Make sure that the supplied buffer is not \c NULL and that you actuallysupport the typecode.\param code The type_code this data is.\param buffer The buffer to unflatten the data from.\param size The size of the data.\returns A status code.\retval B_OK The object is unflattened.\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.\retval B_BAD_TYPE You don't support data with this \a code.\since BeOS R3*//*!\fn virtual BFlattenable::~BFlattenable()\brief Destructor. Does nothing.\since Haiku R1*/