Archiving Plugin Data With The data Type
<< previous | Chapter 13. Plugins | next >>

## Archiving Plugin Data With The data Type

The `data` type is used for archiving and dearchiving custom binary data. If a plugin creates a large internal block of data, for example, how could this data be archived? The `pointer` type cannot be archived because breve doesn't know the structure or size of the data that the pointer is referring to. The type `data` is therefore used to hold a linear block of data of a known type.

In order for plugin data to be stored in a breve archive, the data must be made into a `data` type. Internally, this is represented as the C structure `brData`. The following functions are declared in the plugin header file and will allow you to create and free `brData` structures:

    brData *brDataNew(void *data, int length);
    void brDataFree(brData *data);

To archive and dearchive data from a plugin object, you'll need one internal function to serialize and encode the state of your plugin object and another to deserialize and decode the object. For instance, consider a plugin which deals with large matrices, say 100x100 doubles. When the simulation is to be archived, the matrix needs to be encoded into an `brData` struct and returned to the object. When the simulation is to be dearchived, the `brData` needs to be decoded back into a matrix.

Here's how these functions might look:

    int archiveMatrix(brEval arguments[], brEval *result, void *instance) {
            // assume that the plugin object passes us the pointer to its matrix
            // also assume that the size of the matrix is 100x100 doubles

            double **matrix = BRPOINTER(&arguments[0]);

            BRDATA(result) = brDataNew(matrix, 100 * 100 * sizeof(double));

            return EC_OK;
    }

    int dearchiveMatrix(brEval arguments[], brEval *result, void *instance) {
            brData *matrixData = BRDATA(&arguments[0]);
            double **matrix = malloc(100 * 100 * sizeof(double));

            memcpy(matrix, matrixData->data, 100 * 100 * sizeof(double));

            // now we return the matrix pointer to the object, and the state
            // of the object is restored!

            BRPOINTER(result) = matrix;

            return EC_OK;
    }

We also need to modify the `archive` and `dearchive` methods of our breve plugin object to call the new functions:

    + to archive:
            # convert the internal data to a "data" type
            matrixData = archiveMatrix(matrixPointer).

    + to dearchive:
            # convert the "data" type back to internal data
            matrixPointer = dearchiveMatrix(matrixData).

<< previous | Up | next >>
Building Plugins | Table of Contents | Using Plugins in Simulations