Class StructDataEditor

• Defined in File struct-data-editor.h

Class Documentation

class StructDataEditor

Convenience class provided to make easier the process of reading data from, and writing data to, memory described by a Struct metadata instance.

This class is provided to make the somewhat tedious task of accessing struct field data residing in arbitary memory, described only by an instance of Struct. This is often the case with clients of this GPA Framework, as the GPA Framework strives to maintain API-independence.

Without this facility for "reflection" of API-specific structures, the GPA Framework client would also need to possess the original API header files where these structures are defined, in order to be able to make any sense of a block of memory known to contain the contents of a known API structure.

However, armed only with a pointer to anonymous memory and a pointer to a Struct that describes that memory, the GPA Framework client can readily read (and write, where applicable) the struct member contents almost as easily as if they had the original API header files.

Public Types

enum Result

Values:

enumerator kError

Generic error condition.

enumerator kGetSuccess

Get operation succeeded.

enumerator kGetInvalidTypeConversion

Get operation attempted with invalid template type parameter for field type.

enumerator kSetSuccess

Set operation succeeded.

enumerator kSetInvalidTypeConversion

Set operation attempted with invalid template type parameter for field type.

enumerator kSetReadOnly

Set operation attempted on read-only data.

Public Functions

StructDataEditor(void const *data, Struct const *structDef)

Constructor for read-only data.

Parameters

• data -- Pointer to constant (immutable) memory.

• structDef -- Struct instance describing the memory.

StructDataEditor(void *data, Struct const *structDef)

Constructor for read-write data.

Parameters

• data -- Pointer to mutable memory.

• structDef -- Struct instance describing the memory.

StructDataEditor(void const *data, Union const *unionDef)

Constructor for read-only data.

Parameters

• data -- Pointer to constant (immutable) memory.

• unionDef -- Struct instance describing the memory.

StructDataEditor(void *data, Union const *unionDef)

Constructor for read-write data.

Parameters

• data -- Pointer to mutable memory.

• unionDef -- Struct instance describing the memory.

bool ReadOnly() const

Convenience method to determine if the data is read-only.

Note

This property is determined by which constructor is called, and cannot be changed post-construction.

Returns

true if the data is immutable, false otherwise.

Struct const *StructDef() const

Access the Struct instance used to construct this editor.

Returns

Struct instance passed to the constructor(s).

Union const *UnionDef() const

Access the Union instance used to construct this editor.

Returns

Union instance passed to the constructor(s).

template<typename T>
T Get(Field const *field, Result *result = nullptr) const

Fetch data from memory.

This template method is provided for easier access to data described by the field parameter. Given a valid Field instance (non-null, with a Field that was obtained from the Struct used to construct this editor), this method returns a copy of the field data, and the result code from the operation in the result parameter. If any required data is missing, null or not in order, this method will return the "zero equivalent" for the data requested and the error code in result.

Parameters

• field -- [in] A Field instance obtained from the Struct used to construct this editor

• result -- [out] Provides the result code of the get operation

Returns

If result is Result::kGetSuccess, a copy of the data requested; otherwise, this method returns the zero-equivalent of the field type and the error condition is reported in result.

template<typename T>
Result Set(Field const *field, T value)

Set field values to memory.

Given a Field instance obtained from the Struct used to construct this editor, and a value whose type matches the type accepted by (or convertible to the type accepted by) the field, this method will update the memory with value and return a result code appropriately.

Note

This method requires that ReadOnly() return false.

Parameters

• field -- [in] A Field instance obtained from the Struct used to construct this editor

• value -- [in] The value with which to update the field.

Returns

The following Result codes are possible:

• Result::kSetSuccess - The operation succeeded and memory was updated

• Result::kSetInvalidTypeConversion - The operation failed because the provided type could not be converted to a type accepted by the field

• Result::kSetReadOnly - The operation failed because the memory is immutable

Protected Attributes

void const *mData

void *mMutableData

Struct const *mStructDef

Union const *mUnionDef