BFlattenable Class Reference

Interface for classes that can flatten and unflatten themselves to a stream of bytes. More...

Inherited by BAffineTransform, BNetworkAddress, BParameter, BParameterGroup, BParameterWeb, BPath, BPropertyInfo, BStringList, and dormant_flavor_info.

Public Member Functions
virtual	~BFlattenable ()
	Destructor. Does nothing.
virtual bool	AllowsTypeCode (type_code code) const
	Get whether or not the supplied type_code is supported.
virtual status_t	Flatten (void *buffer, ssize_t size) const =0
	Pure virtual that should flatten the object into the supplied buffer.
virtual ssize_t	FlattenedSize () const =0
	Pure virtual that should return the size of the flattened object in bytes.
virtual bool	IsFixedSize () const =0
	Pure virtual that should return whether or not flattened objects of this type always have a fixed size.
virtual type_code	TypeCode () const =0
	Pure virtual that returns the type_code this class flattens to.
virtual status_t	Unflatten (type_code code, const void *buffer, ssize_t size)=0
	Pure virtual that should unflatten the buffer and put the contents into the current object.

Detailed Description

Interface for classes that can flatten and unflatten themselves to a stream of bytes.

It is convenient that objects can be stored as a flat stream of bytes. In this way, they can be written to disk, exchanged between applications or send over networks. This ability, known as marshaling in many other programming languages, is not native to C++. The Haiku API has created a universal interface that classes have if they are able to be flattened. This class defines the interface. This class does nothing on its own, and therefore contains pure virtual functions. By inheriting this class and implementing the methods in your own class, you will be able to use your objects as flattenable objects throughout the Haiku API.

Flattened objects can be used for example when sending messages within an application or between applications. The BMessage class uses the interface to store and transmit custom classes.

If you want to be able to flatten your objects, you will need to implement various methods. Flatten() and Unflatten() are where the magic happen. These methods handle the actual flattening and unflattening. To identify flattened data in for example BMessage, the object has a type_code. Type codes are four byte long integers. You can choose to flatten to one of the existing types, if you are certain that you are compatible to those, but you'll usually define your own type. Your best option is by using a multicharacter constant, such as 'STRI'. Implement TypeCode() to return the type you support. Implement FlattenedSize() to make sure that other objects can provide the right buffers. Implement IsFixedSize() to return whether your objects always store to a fixed size.

See the following example:

type_code CUSTOM_STRING_TYPE = 'CUST';
 
class CustomString : public BFlattenable {
public:
    char data[100];
 
    // from BFlattenable
    bool 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;
    };
};

Have a look at TypeConstants.h for a list of all the types that the Haiku API defines.

The Haiku API has a second interface for storing objects, which is with BArchivable. BArchivable is for more complex cases. Instead of one flat datastream, it stores an object in a BMessage. In that way you can reflect internals of a class better. It also provides an interface for instantiating objects, that is, for objects to restore themselves from a BMessage. In essence, BArchivable is more suitable for objects that are alive. In short BFlattenable is for data objects, BArchivable is for 'live' objects.

Other classes in the API that support flattening and unflattening are for example BMessage, which enables you to conveniently write flattened data to disk. Another example is BPath. Because of that you can store paths and send them over via messages. Throughout the Haiku API you will find classes that provide the flattening interface.

Since

BeOS R3

Constructor & Destructor Documentation

~BFlattenable()

BFlattenable::~BFlattenable ( )

virtual

Destructor. Does nothing.

Since

Haiku R1

Member Function Documentation

AllowsTypeCode()

bool BFlattenable::AllowsTypeCode ( type_code  code ) const

virtual

Get whether or not the supplied type_code is supported.

This default implementation checks the code argument against the type_code returned by TypeCode().

Parameters

code	The type_code constant you want to check for.

Returns

Whether or not the supplied type_code is supported.

Return values

true	The type_code is supported.
false	The type_code is not supported.

Since

BeOS R3

Reimplemented in BPropertyInfo, BPath, and BStringList.

Flatten()

status_t BFlattenable::Flatten ( void *  buffer, ssize_t  size  ) const

pure virtual

Pure virtual that should flatten the object into the supplied buffer.

Please make sure that you check that the supplied buffer is not a NULL pointer. Also make sure that the size of the flattened object does isn't larger than the size of the buffer.

Parameters

buffer	The buffer to flatten in.
size	The size of the buffer.

Return values

B_OK	The object was flattened.
B_NO_MEMORY	The buffer was smaller than required.
B_BAD_VALUE	The buffer was a NULL pointer.

Since

BeOS R3

Implemented in BPropertyInfo, BAffineTransform, BPath, and BStringList.

FlattenedSize()

ssize_t BFlattenable::FlattenedSize ( ) const

pure virtual

Pure virtual that should return the size of the flattened object in bytes.

Since

BeOS R3

Implemented in BPropertyInfo, BAffineTransform, BPath, and BStringList.

IsFixedSize()

bool BFlattenable::IsFixedSize ( ) const

pure virtual

Pure virtual that should return whether or not flattened objects of this type always have a fixed size.

Returns

Should return whether or not the flattened objects of this type always have a fixed size.

Since

BeOS R3

Implemented in BPropertyInfo, BAffineTransform, BPath, and BStringList.

TypeCode()

type_code BFlattenable::TypeCode ( ) const

pure virtual

Pure virtual that returns the type_code this class flattens to.

Returns

Either one of the existing typecodes found in TypeConstants.h if your class actually is compatible to those formats, or a custom four-byte integer constant if not.

Since

BeOS R3

Implemented in BPropertyInfo, BAffineTransform, BPath, and BStringList.

Unflatten()

status_t BFlattenable::Unflatten ( type_code  code, const void *  buffer, ssize_t  size  )

pure virtual

Pure virtual that should unflatten the buffer and put the contents into the current object.

Make sure that the supplied buffer is not NULL and that you actually support the typecode.

Parameters

code	The type_code this data is.
buffer	The buffer to unflatten the data from.
size	The size of the data.

Returns

A status code.

Return values

B_OK	The object is unflattened.
B_BAD_VALUE	The buffer pointer is NULL or the data is invalid.
B_BAD_TYPE	You don't support data with this code.

Since

BeOS R3

Implemented in BPropertyInfo, BAffineTransform, BPath, and BStringList.