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).