ClassInterface Class Reference

#include <objectbase.h>

Detailed Description

A ClassInterface object represents an object class at runtime, see vinterfaces. Such an object class can be published by MAXON_DECLARATION, and it is then typically defined by MAXON_COMPONENT_CLASS_REGISTER.

A class consists of several components (see ComponentDescriptor), each of which may implement several virtual interfaces (declared by MAXON_INTERFACE). The class itself then implements all interfaces of all of its components. Information about components and interfaces can be obtained from the ClassInfo object returned by GetClassInfo().

After allocation of a class, you have to add the components of which it shall consist via AddComponent() or AddComponents(). Afterwards, you can invoke Finalize() to make the class ready for use. From then on, only const methods may be invoked on a class. If you use GenericClass or Class to access a class, this is automatically guaranteed as those are const references. If you don't invoke Finalize(), this will be done implicitly when the first instance of the class is allocated.

The MAXON_COMPONENT_CLASS_REGISTER and MAXON_COMPONENT_OBJECT_REGISTER macros greatly simplify the setup of a class.

ClassInterface objects are automatically registered at the Classes registry, so with

Class<MyType> cls = Classes::Get<MyType>("com.foo.class.bar");

you can look for the class with identifier "com.foo.class.bar". MyType is the expected reference type of instances of the class.

Public Types
enum class	KIND {   NORMAL ,   SINGLETON ,   ABSTRACT }

Public Member Functions
enum maxon::ClassInterface::KIND	MAXON_ENUM_LIST_CLASS (KIND)
MAXON_METHOD const Id &	GetId () const
MAXON_METHOD KIND	GetKind () const
MAXON_METHOD Int	GetSize () const
MAXON_METHOD Block< const ComponentInfo *const >	GetComponents () const
MAXON_METHOD Result< void >	AddComponent (const ComponentDescriptor &component)
MAXON_METHOD void	RemoveLastComponent ()
MAXON_METHOD Result< void >	AddComponents (const Class<> &cls)
MAXON_METHOD Result< void >	Finalize ()
MAXON_METHOD Bool	IsFinalized () const
MAXON_METHOD const Block< const InterfaceReference *const > &	GetImplementedInterfaces () const
MAXON_METHOD const DataType &	GetDataType () const
MAXON_METHOD Result< typename maxon::details::ClassGetNonConst< REF >::type >	Create () const
MAXON_METHOD Result< ObjectInterface * >	CreatePointer (Int size=-1) const
MAXON_FUNCTION Bool	Implements (const InterfaceReference &iref) const
template<typename I >
MAXON_FUNCTION Bool	Implements () const
MAXON_METHOD Bool	IsSubclassOf (const Class<> &other) const
MAXON_METHOD String	ToString (const FormatStatement *formatStatement=nullptr) const
MAXON_METHOD const DataDictionary &	GetMetaData () const
MAXON_METHOD void	InitMetaData (DataDictionary &&data)
void	PrivateInitMetaData (ResultOk< void > &&data)
template<typename T >
void	PrivateInitMetaData (Result< T > &&data)

Static Public Member Functions
static MAXON_METHOD ClassInterface *	Alloc (MAXON_SOURCE_LOCATION_DECLARATION, const Id &cid, KIND kind=KIND::NORMAL)
static MAXON_METHOD void	DeleteInstance (const ObjectInterface *object)
static MAXON_METHOD void	DestructInstance (const ObjectInterface *object)

Protected Member Functions
MAXON_METHOD const ClassInfo *	GetInfo () const
MAXON_METHOD Result< Int >	AddProxyComponent (const ComponentDescriptor &component, Bool shared)

Static Protected Member Functions
static MAXON_METHOD Result< void >	CopyInstance (ObjectInterface *dest, const ObjectInterface *src)
static MAXON_METHOD void *	GetOrCreateMTable (ClassInfo *info, const InterfaceReference &i)
static const InterfaceInfo *	GetValidInterfaceInfo (const ClassInfo *info, Int offset)

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (ClassInterface, MAXON_REFERENCE_CONST, "net.maxon.interface.class", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))
	MAXON_GENERIC ((Out) typename REF=ObjectRef)

Friends
class	ObjectInterface
class	ObjectModel
class	ComponentDescriptor
class	reflection::ProxyImpl
template<typename , typename , Bool >
struct	CombinedMTableBase
template<typename , typename , typename , typename... >
class	ComponentWithBase

Member Enumeration Documentation

KIND

enum KIND

strong

An object class is of one of the kinds defined by this enum.

Enumerator
NORMAL	A normal object class.
SINGLETON	A singleton object class, i.e., a class with exactly one instance. The instance can be obtained with Create().
ABSTRACT	An abstract object class. Create() will return an UnsupportedOperationError.

Member Function Documentation

MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( ClassInterface  , MAXON_REFERENCE_CONST  , "net.maxon.interface.class"  , MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")    )

private

MAXON_GENERIC()

MAXON_GENERIC ( (Out) typename  REF = ObjectRef )

private

MAXON_ENUM_LIST_CLASS()

enum maxon::ClassInterface::KIND MAXON_ENUM_LIST_CLASS

(

KIND

)

Alloc()

static MAXON_METHOD ClassInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  , const Id &  cid, KIND  kind = KIND::NORMAL  )

static

Allocates a new ClassInterface object with a given identifier. The new class doesn't contain any components, you have to add them afterwards by AddComponent() or AddComponents(), and to finally invoke Finalize to complete the class.

Parameters

[in]	allocLocation	Pass MAXON_SOURCE_LOCATION(_NAME) to add the current source line and file.
[in]	cid	Unique identifier for the class.
[in]	kind	Use KIND::SINGLETON for a singleton class or KIND::ABSTRACT for an abstract class.

Returns

Pointer to a new ClassInterface object.

GetId()

MAXON_METHOD const Id& GetId

(

)

const

Returns the identifier of this object class. Class identifiers are unique and should follow the naming convention of the Maxon API:

• It starts with reverse domain name notation of an internet domain you own (such as net.maxon in the case of MAXON).
• Then it can have a part which narrows down the area to which the class belongs (such as image or node). In the case of MAXON-provided classes this part often relates to the module in which the classes are implemented.
• Then there's class followed by a local name of the class. Examples for complete ids are net.maxon.class.hierarchyobject, net.maxon.image.class.mediaoutputtexture or net.maxon.node.class.nodesystem.

  Returns

  Class identifier.

GetKind()

MAXON_METHOD KIND GetKind

(

)

const

Returns the kind of this object class, see KIND.

Returns

Kind of this object class.

GetSize()

MAXON_METHOD Int GetSize

(

)

const

Returns the size in bytes of an instance of this class.

Returns

Byte size of an instance of this class.

GetComponents()

MAXON_METHOD Block<const ComponentInfo* const> GetComponents

(

)

const

Returns a list of all class components. The components are in order of registration.

Returns

Reference to the list of components.

AddComponent()

MAXON_METHOD Result<void> AddComponent

(

const ComponentDescriptor &

component

)

Adds a component to this class. The class must not yet have been finalized (by invocation of Finalize()). The added component will overwrite the vtables of the interfaces it implements (see InterfaceInfo), but the previous values are stored (in the _supervtable member of ComponentInfo) and used by the Super function of the component implementation.

Parameters

[in]

component

Component to add.

Returns

OK on success. In the case of an error, the class hasn't been changed.

See also

AddComponents

RemoveLastComponent()

MAXON_METHOD void RemoveLastComponent

(

)

@MAXON_ANNOTATION{refclass=false}

AddComponents()

MAXON_METHOD Result<void> AddComponents

(

const Class<> &

cls

)

Adds all components of class cls to this class. This class must not yet have been finalized (by invocation of Finalize()). The addition is done in the same order as for the original class. Afterwards, cls can be seen as a base class of this class.

Parameters

[in]

cls

Implementation class of the component to add.

Returns

OK on success. In the case of an error, the class shouldn't be used.

See also

AddComponent

Finalize()

MAXON_METHOD Result<void> Finalize

(

)

Finalizes this class so that it can be used afterwards. The class has to be built before by AddComponent(). Some internal data will be set-up for the class so that it is ready for use. If you don't invoke Finalize(), it will be done implicitly when an object of the class is instantiated for the first time.

Returns

OK on success. If an error occurred, the class shouldn't be used.

See also

AddComponent

IsFinalized()

MAXON_METHOD Bool IsFinalized

(

)

const

Returns true if the class has been finalized successfully before.

Returns

True if the class is finalized.

See also

Finalize

GetImplementedInterfaces()

MAXON_METHOD const Block<const InterfaceReference* const>& GetImplementedInterfaces

(

)

const

Returns a block of all interfaces which this class implements. For each interface, the block will also contain its base interfaces. The interfaces will be sorted according to their depth and, at second level, to their ids.

Returns

Block of all implemented interfaces.

GetDataType()

MAXON_METHOD const DataType& GetDataType

(

)

const

Returns the data type corresponding to the set of implemented interfaces of this class. For an abstract class this will return nullptr.

Returns

Data type of this class.

Create()

MAXON_METHOD Result<typename maxon::details::ClassGetNonConst<REF>::type> Create

(

)

const

Constructs a new instance of this class. This will invoke the constructors of each component in the order of addition, and then the InitComponent functions of each component. When one of the InitComponent functions fails with an error, FreeComponent will be invoked on the previous (already initialized) components, the component destructors will be invoked, the memory will by freed, and Create() returns the error.

For a singleton class, this doesn't create a new instance, but returns the singleton instance of this class. This instance is automatically created on finalization of the class.

For an abstract class, this will always return an UnsupportedOperationError.

Returns

Reference to new instance, or an error if the allocation or initialization failed.

CreatePointer()

MAXON_METHOD Result<ObjectInterface*> CreatePointer

(

Int

size = -1

)

const

Constructs a new instance of this class. This will invoke the constructors of each component in the order of addition, and then the InitComponent functions of each component. When one of the InitComponent functions fails with an error, FreeComponent will be invoked on the previous (already initialized) components, the component destructors will be invoked, the memory will by freed, and CreatePointer() returns the error.

For an abstract class, this will always return an UnsupportedOperationError.

The reference counter of the returned object will be zero.

Parameters

[in]

size

Optional memory size for the allocation. This can be used if the object needs some extra space.

Returns

Pointer to the new instance, or an error if the allocation or initialization failed.

Warning

This function must not be used for a singleton class, use Create() instead.

@MAXON_ANNOTATION{refclass=false}

Implements() [1/2]

MAXON_FUNCTION Bool Implements

(

const InterfaceReference &

iref

)

const

Checks if the class implements the interface iref. This means that this class contains a component implementing the interface.

Parameters

[in]

iref

An interface.

Returns

True if this class implements the interface, false otherwise.

Implements() [2/2]

MAXON_FUNCTION Bool Implements

(

)

const

Checks if the class implements the interface I. This means that this class contains a component implementing the interface.

Template Parameters

I	An interface.

Returns

True if this class implements the interface I, false otherwise.

IsSubclassOf()

MAXON_METHOD Bool IsSubclassOf

(

const Class<> &

other

)

const

Checks if this class is a subclass of other, i.e., if this class has all components of other.

Parameters

[in]

other

Another class.

Returns

True if this class is a subclass of other, false otherwise.

ToString()

MAXON_METHOD String ToString

(

const FormatStatement *

formatStatement = nullptr

)

const

Returns a readable string of the content.

Parameters

[in]

formatStatement

Nullptr or additional formatting instruction. Currently no additional formatting instructions are supported.

Returns

The converted result. The representation consists of the class identifier prefixed by "class ".

GetMetaData()

MAXON_METHOD const DataDictionary& GetMetaData

(

)

const

Returns the meta data of this class. Usually that's a null reference, but one can set up the meta data either by InitMetaData() or by adding a function CreateClassMetaData() to the component which is used to setup a class:

class MyComponent : public Component<MyComponent, MyInterface>
{
  MAXON_COMPONENT();
public:
  ...
  static Result<DataDictionary> CreateClassMetaData()
  {
    iferr_scope;
    DataDictionary dict;
    ... // setup dict
    return dict;
  }
};
 
MAXON_COMPONENT_CLASS_REGISTER(MyComponent, "net.maxon.class.myclass");

Returns

The meta data of this class.

InitMetaData()

MAXON_METHOD void InitMetaData

(

DataDictionary &&

data

)

Initializes the meta data (to be returned by GetMetaData()) for this class. You can also setup the meta data by a function CreateClassMetaData() in a component, see GetMetaData().

Parameters

[in]

data

The meta data.

PrivateInitMetaData() [1/2]

void PrivateInitMetaData

(

ResultOk< void > &&

data

)

PrivateInitMetaData() [2/2]

void PrivateInitMetaData

(

Result< T > &&

data

)

DeleteInstance()

static MAXON_METHOD void DeleteInstance ( const ObjectInterface *  object )

static

Deletes an instance of a class. This is automatically invoked if the reference count of the instance reaches zero.

Parameters

[in]

object

Instance to delete, must not be nullptr.

DestructInstance()

static MAXON_METHOD void DestructInstance ( const ObjectInterface *  object )

static

Destructs an instance of a class. This is automatically invoked if the reference count of the instance reaches zero.

Parameters

[in]

object

Instance to destruct, must not be nullptr.

CopyInstance()

static MAXON_METHOD Result<void> CopyInstance ( ObjectInterface *  dest, const ObjectInterface *  src  )

staticprotected

Copies the component data of objects. This is invoked by ObjectInterface::CopyFrom.

Parameters

[out]	dest	Destination object, may be nullptr.
[in]	src	Source object, may be nullptr.

Returns

OK on success. This will report a NullptrError if any of the arguments is nullptr.

GetInfo()

MAXON_METHOD const ClassInfo* GetInfo ( ) const

protected

Returns the ClassInfo object of this class. This is only needed internally.

Returns

ClassInfo object of this class. Will never be nullptr.

GetOrCreateMTable()

static MAXON_METHOD void* GetOrCreateMTable ( ClassInfo *  info, const InterfaceReference &  i  )

staticprotected

Returns a pointer to the MTable for the interface having the specified offset. The memory for the MTable is allocated if necessary.

Parameters

[in]	info	ClassInfo object.
[in]	i	The interface for which the method table shall be obtained.

Returns

Pointer to the MTable of the interface, or nullptr if the MTable allocation failed.

GetValidInterfaceInfo()

static const InterfaceInfo* GetValidInterfaceInfo ( const ClassInfo *  info, Int  offset  )

staticprotected

Returns the InterfaceInfo for the interface having the specified offset.

Parameters

[in]	info	ClassInfo object of the class in question.
[in]	offset	Offset of the interface within the interface table.

Returns

InterfaceInfo object, or nullptr if the class doesn't implement the interface.

AddProxyComponent()

MAXON_METHOD Result<Int> AddProxyComponent ( const ComponentDescriptor &  component, Bool  shared  )

protected

Friends And Related Function Documentation

ObjectInterface

friend class ObjectInterface

friend

ObjectModel

friend class ObjectModel

friend

ComponentDescriptor

friend class ComponentDescriptor

friend

reflection::ProxyImpl

friend class reflection::ProxyImpl

friend

CombinedMTableBase

friend struct CombinedMTableBase

friend

ComponentWithBase

friend class ComponentWithBase

friend