# The Support Kit: BFlattenable

Derived from: none

Declared in: be/support/Flattenable.h

Library: libbe.so

## Overview

As its name implies, the BFlattenable class declares a protocol for objects that can be flattened--written to an untyped buffer of bytes--and unflattened from the buffer. By implementing this protocol, a class gives others the ability to manipulate its objects in a flexible manner. Currently, only the BMessage class, through its `AddFlat()` and `FindFlat()` functions, declares an API that can deal with BFlattenable objects. The BPath class in the Storage Kit derives from BFlattenable.

As this class merely declares a protocol for other classes to implement, it doesn't include a constructor or destructor.

## Member Functions

### AllowsTypeCode() see TypeCode()

### Flatten(), Unflatten()

          virtual status_t Flatten(void *buffer, ssize_t numBytes) const = 0

          virtual status_t Unflatten(type_code code, const void *buffer, ssize_t numBytes) = 0

`Flatten()` is implemented by derived classes to write the object into the buffer. There are numBytes bytes of memory available at the buffer address. If this isn't at least as much memory as the `FlattenedSize()` function says is necessary, `Flatten()` should return an error. If successful, it should return `B_OK`.

`Unflatten()` is implemented by derived classes to set object values from numBytes bytes of data taken from the buffer. However, it should read the data only if the type code it's passed indicates that the data is a type that it supports--that is, only if its `AllowsTypeCode()` function returns `true` for the code. If successful in reconstructing the object from the flattened data, `Unflatten()` should return `B_OK`. If not, it should return `B_ERROR` or a more descriptive error code.

### FlattenedSize()

          virtual ssize_t FlattenedSize(void) const = 0

Implemented by derived classes to return the amount of memory needed to hold the flattened object. This is the minimal amount that must be allocated and passed to `Flatten()`.

### IsFixedSize()

          virtual bool IsFixedSize(void) const = 0

Implemented by derived classes to return `true` if all instances of the class take up the same amount of memory when they're flattened, and `false` if their flattened sizes can differ. The sizes will differ, for example, if a variable-length string is part of the flattened data.

### TypeCode(), AllowsTypeCode()

          virtual type_code TypeCode(void) const = 0

          virtual bool AllowsTypeCode(type_code code) const

`TypeCode()` is implemented by derived classes to return the type code that identifies the class type. The code is used to identify an instance of the class in its flattened state, for example when it's added to a BMessage.

`AllowsType()` returns `true` if the code it's passed matches the code returned by `TypeCode()` and `false` if not. If can be modified in derived classes to apply a more liberal standard--to allow more than one type code to identify the object.

See also: `BMessage::AddData()`

### Unflatten() see Flatten()

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.