API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2
See Also
- IValueModel - IValueModel_GetValue - IValueModel_AdaptGet - IValueModel_SetValue - IValueModel_AdaptSet
This type definition specifies the prototype for the function pointer used to store specific pieces of data stored in a value model. The value model allows objects to attach themselves to data of some arbitrary size and structure. The data may be as simple and straightforward as a single boolean or integer value -- or it might be very complex, comprised of many fields, structures or could even be dynamic. On occasion, it many be desirable for a value model to alter only a specific portion of a given data structure.
For example, a value model that stores baseball statistics would likely possess fields that recorded player names, hits, at bats, RBI, homeruns,and perhaps a JPEG image of that player. BREW calls the PFNADAPTSET callback (when present) each time IValueModel_SetValue() is called. The callback then may then selectively store only specific portions of the data structure -- perhaps just the at bats and hits in the example above if the application was updating stored information play-by-play as a game was taking place. The callback will provide the code required to store sepcific fields within an existing value model record, rather than overwriting an entire record.
  • pvCtx:       A pointer to a private context controlled by the value model.  The callback
                     may use this context information in determing how or where to store specific
                     pieces of information within a record being written to a given value model.
                     For example, 'pvCtx' could identify a specific field to be stored, known only
                     to the value model.
  • pValueIn:    The value to be stored into the value model.  Depending on the complexity of
                     the data being modeled, 'pValueIn' may be as simple as a boolean or integer
                     value, but may also be passed as a pointer to a more complex data structure.
  • nLen:        When 'pValueIn' is a pointer to the data to be stored, 'nLen' is the length
                     of that data in bytes.  Otherwise, less complex value models may pass the
                     data length as zero.
  • ppValueOut:  A pointer to the current data stored in the value model.  The value model's
                     PFNADAPTSET function might use the current data as the basis for storing the
                     next piece of data.
  • pnLenOut:    The length of the data currently stored in the value model.  The value model's
                     PFNADAPTSET function might use the length of the current data as the basis for
                     storing the next piece of data.
  • ppfn:        Pointer to the callback callback routine that will be used to free the data
                     stored in the value model.  It is importan to note that this is the callback
                     that should be associated with the _new_ data being stored and is not
                     (necessarily) the same callback that would be used to free any exisiting
  •     typedef void (*PFNADAPTSET)(void *pvCtx, void *pValueIn, int nLen, void **ppValueOut, int *pnLenOut, PFNVALUEFREE *ppfn);
The PFNADAPTSET callback is issued during calls to IValueModel_SetValue(). Use IValueModel_AdaptSet() to initialize the callback and any private data the callback will need prior to calling IValueModel_SetValue(). When the callback is not present (i.e. NULL) IValueModel_SetValue() will retrieve _all_ the data associated with a given value model.