IBaseObject Struct Reference

Inherits IUnknown.

Inherited by IAddressInfoBuilder, IAddressInfoPrivate, IAllocator, IArgumentInfo, IAuthenticationProvider, IAwaitable, IBinaryData, IBlockReaderBuilder, IBoolean, ICallableInfo, ICloneable, ICoercer, IComparable, IComplexNumber, IComponentDeserializeContext, IComponentHolder, IComponentPrivate, IComponentStatusContainer, IComponentStatusContainerPrivate, IComponentType, IComponentTypeBuilder, IComponentUpdateContext, IConfigProvider, IConnection, IConnectionInternal, IContext, IContextInternal, IConvertible, ICoreType, IDataDescriptor, IDataDescriptorBuilder, IDataRule, IDataRuleBuilder, IDataRuleCalcPrivate, IDeleter, IDeserializeComponent, IDeserializer, IDeviceDomain, IDeviceInfoInternal, IDevicePrivate, IDict, IDictElementType, IDimension, IDimensionBuilder, IDimensionRule, IDimensionRuleBuilder, IDiscoveryServer, IEnumeration, IErrorInfo, IEvalValue, IEvent, IEventArgs, IEventHandler, IFloat, IFreezable, IFunction, IFunctionBlockWrapper, IGraphVisualization, IInputPortNotifications, IInputPortPrivate, IInspectable, IInstanceBuilder, IInteger, IIterable, IIterator, ILastMessageLoggerSinkPrivate, IList, IListElementType, ILogFileInfo, ILogFileInfoBuilder, ILogger, ILoggerComponent, ILoggerSink, ILoggerSinkBasePrivate, ILoggerThreadPool, ILoggerThreadPoolPrivate, IMirroredSignalPrivate, IMockChannel, IMockDefaultDevice, IModule, IModuleManager, IModuleManagerUtils, IMultiReaderBuilder, INumber, IOwnable, IPacket, IPacketDestructCallback, IPermissionManager, IPermissionManagerInternal, IPermissionMaskBuilder, IPermissions, IPermissionsBuilder, IPermissionsInternal, IProcedure, IProperty, IPropertyBuilder, IPropertyInternal, IPropertyObject, IPropertyObjectClassBuilder, IPropertyObjectInternal, IPropertyObjectProtected, IRange, IRatio, IReader, IReaderConfig, IReaderStatus, IRecursiveSearch, IReferenceDomainInfo, IReferenceDomainInfoBuilder, IRemovable, IReusableDataPacket, IRulePrivate, IScaling, IScalingBuilder, IScalingCalcPrivate, IScheduler, ISearchFilter, ISerializable, ISerializedList, ISerializedObject, ISerializer, ISignalEvents, ISignalPrivate, IStreaming, IStreamingPrivate, IStreamReaderBuilder, IString, IStruct, IStructBuilder, ISupportsWeakRef, ISyncComponentPrivate, ITags, ITagsPrivate, ITailReaderBuilder, ITask, ITaskInternal, IType, ITypeManager, ITypeManagerPrivate, IUnit, IUnitBuilder, IUpdatable, IUser, IUserInternal, IUserLock, IValidator, IVersionInfo, IWeakRef, and IWork.

Collaboration diagram for IBaseObject:

Detailed Description

Extends IUnknown by providing additional methods for borrowing interfaces, hashing, and equality comparison. All openDAQ objects implement IBaseObject interface or its descendants. Hashing and equality comparison provides the ability to use the object as an element in dictionaries and lists. Classes that implement any interface derived from IBaseObject should be derived from ImplementationOf class, which provides the default implementation of IBaseObject interface methods.

Available factories:

// Creates a new BaseObject. Throws exception if not successful.
IBaseObject* BaseObject_Create()
 
// Creates a new BaseObject. Returns error code if not successful.
ErrCode createBaseObject(IBaseObject** obj)

Public Member Functions
virtual ErrCode INTERFACE_FUNC	borrowInterface (const IntfID &intfID, void **obj) const =0
	Returns another interface which is supported by the object without incrementing the reference count. More...
virtual ErrCode INTERFACE_FUNC	dispose ()=0
	Disposes all references held by the object. More...
virtual ErrCode INTERFACE_FUNC	getHashCode (SizeT *hashCode)=0
	Returns hash code of the object. More...
virtual ErrCode INTERFACE_FUNC	equals (IBaseObject *other, Bool *equal) const =0
	Compares object to another object for equality. More...
virtual ErrCode INTERFACE_FUNC	toString (CharPtr *str)=0
	Returns a string representation of the object. More...
Public Member Functions inherited from IUnknown
virtual ErrCode INTERFACE_FUNC	queryInterface (const IntfID &intfID, void **obj)=0
	Returns another interface which is supported by the object and increments the reference count. More...
virtual int INTERFACE_FUNC	addRef ()=0
	Increments the reference count for an interface on an object. More...
virtual int INTERFACE_FUNC	releaseRef ()=0
	Decrements the reference count for an interface on an object. More...

Member Function Documentation

borrowInterface()

virtual ErrCode INTERFACE_FUNC borrowInterface ( const IntfID &  intfID, void **  obj  ) const

pure virtual

Returns another interface which is supported by the object without incrementing the reference count.

Parameters

	intfID	Interface ID of requested interface.
[out]	obj	Pointer to the new interface.

Returns

OPENDAQ_SUCCESS if succeeded, error code otherwise.

This method is similar to queryInterface, however, it does not increment the reference count. Use this method if you need to get another interface to the object and the lifetime of the new interface is shorter than the lifetime of the original interface.

Typical scenario is when an interface is passed as a parameter to a function and in this function you need another interface to the object, but only within the scope of this function call. The object will not be destroyed before the function is exited, because the caller is responsible for holding the reference to the object.

Example:

IUnknown* obj = ...;
 
IBaseObject* baseObj;
auto errCode = obj->borrowInterface(IBaseObject::Id, reinterpret_cast<void**>(&baseObj)), OPENDAQ_SUCCESS);
if (OPENDAQ_FAILED(errCode))
    throw SomeException();
// ... do something with baseObj
// do not call baseObj->releaseRef()

dispose()

virtual ErrCode INTERFACE_FUNC dispose ( )

pure virtual

Disposes all references held by the object.

Returns

OPENDAQ_SUCCESS if succeeded, error code if failed.

An object that holds references to other interfaces must reset these references to null in dispose. This method is called automatically when the reference count drops to zero.

Call this method manually to break cycle references. If two objects have reference to each other, calling dispose will break cycle references.

After dispose is called, the object should not be accessed again, except by calling releaseRef function.

equals()

virtual ErrCode INTERFACE_FUNC equals ( IBaseObject *  other, Bool *  equal  ) const

pure virtual

Compares object to another object for equality.

Parameters

other	Interface to another object for comparison.
equal	Value indicating if the other is equivalent to this one.

For reference objects, it compares the address of the object. For value objects, such as numbers and strings, it compares values.

ImplementationOf which provides default implementation of IBaseObject uses pointer address to compare for equality.

getHashCode()

virtual ErrCode INTERFACE_FUNC getHashCode ( SizeT *  hashCode )

pure virtual

Returns hash code of the object.

Parameters

[out]

hashCode

Hash code.

Returns

OPENDAQ_SUCCESS if succeeded, error code otherwise.

The object should calculate and return the hash code. For reference objects, it is usually calculated from pointer address. For value objects, such as numbers and strings, it is calculated from value.

ImplementationOf object which provides default implementation of IBaseObject uses pointer address to calculate hash code.

If the object calculates the hash code from some value stored in the object, it is mandatory to make this value (or the object) immutable. The hash code of the object should not change. If a dictionary stores the object as a key, it will corrupt the hash table.

toString()

virtual ErrCode INTERFACE_FUNC toString ( CharPtr *  str )

pure virtual

Returns a string representation of the object.

Parameters

[out]

str

String representation of the object.

Returns

OPENDAQ_SUCCESS if succeeded, error code otherwise.

Call this method to convert the object to its string representation.

ImplementationOf object which provides default implementation of IBaseObject uses pointer address for string representation.

Return value str should be de-allocated by the caller using daqFreeMemory function.