Feature Access

Functions for accessing properties, methods and lists. More...

Typedefs
typedef void *	CallbackHandle
	A type to create a unique identifier for a callback.

Enumerations
enum	TCallbackType {   ctOnChanged = 0 ,   ctOnReadData = 1 ,   ctOnWriteData = 2 ,   ctOnRefreshCache = 3 }
	Defines the type of callback to register. More...
enum	TComponentFlag {   cfUndefined = 0x0 ,   cfReadAccess = 0x1 ,   cfWriteAccess = 0x2 ,   cfRWAccess = cfReadAccess | cfWriteAccess ,   cfFixedSize = 0x4 ,   cfInvisible = 0x10 ,   cfAllowValueCombinations = 0x20 ,   cfShouldBeDisplayedAsList = 0x40 ,   cfDisallowSerialize = 0x80 ,   cfAlwaysForceClone = 0x100 ,   cfNotAvailable = 0x200 ,   cfNotImplemented = 0x400 ,   cfContainsBinaryData = 0x800 ,   cfShouldBeDisplayedAsEnumeration = 0x1000 ,   cfAlwaysForceUpdate = 0x2000 }
	Flags defining access rights and other component properties. More...
enum	TComponentRepresentation {   crUndefined = 0 ,   crLinear ,   crLogarithmic ,   crBoolean ,   crPureNumber ,   crHexNumber ,   crIPv4Address ,   crMACAddress ,   crFileName ,   crDirectoryName }
	Defines valid recommended representations for features. More...
enum	TComponentType {   ctProp = 0x00010000 ,   ctList = 0x00020000 ,   ctMeth = 0x00040000 ,   ctPropInt = ctProp | vtInt ,   ctPropFloat = ctProp | vtFloat ,   ctPropString = ctProp | vtString ,   ctPropPtr = ctProp | vtPtr ,   ctPropInt64 = ctProp | vtInt64 }
	Allowed components handled by this module. More...
enum	TComponentVisibility {   cvBeginner = 0 ,   cvExpert = 1 ,   cvGuru = 2 ,   cvInvisible = 3 }
	Defines valid recommended visibilities for features. More...
enum	TPROPHANDLING_ERROR {   PROPHANDLING_NO_ERROR = 0 ,   PROPHANDLING_NOT_A_LIST = -2000 ,   PROPHANDLING_NOT_A_PROPERTY = -2001 ,   PROPHANDLING_NOT_A_METHOD = -2002 ,   PROPHANDLING_NO_READ_RIGHTS = -2003 ,   PROPHANDLING_NO_WRITE_RIGHTS = -2004 ,   PROPHANDLING_NO_MODIFY_SIZE_RIGHTS = -2005 ,   PROPHANDLING_INCOMPATIBLE_COMPONENTS = -2006 ,   PROPHANDLING_UNSUPPORTED_PARAMETER = -2008 ,   PROPHANDLING_SIZE_MISMATCH = -2009 ,   PROPHANDLING_IMPLEMENTATION_MISSING = -2010 ,   PROPHANDLING_ACCESSTOKEN_CREATION_FAILED = -2011 ,   PROPHANDLING_INVALID_PROP_VALUE = -2012 ,   PROPHANDLING_PROP_TRANSLATION_TABLE_CORRUPTED = -2013 ,   PROPHANDLING_PROP_VAL_ID_OUT_OF_BOUNDS = -2014 ,   PROPHANDLING_PROP_TRANSLATION_TABLE_NOT_DEFINED = -2015 ,   PROPHANDLING_INVALID_PROP_VALUE_TYPE = -2016 ,   PROPHANDLING_PROP_VAL_TOO_LARGE = -2017 ,   PROPHANDLING_PROP_VAL_TOO_SMALL = -2018 ,   PROPHANDLING_COMPONENT_NOT_FOUND = -2019 ,   PROPHANDLING_LIST_ID_INVALID = -2020 ,   PROPHANDLING_COMPONENT_ID_INVALID = -2021 ,   PROPHANDLING_LIST_ENTRY_OCCUPIED = -2022 ,   PROPHANDLING_COMPONENT_HAS_OWNER_ALREADY = -2023 ,   PROPHANDLING_COMPONENT_ALREADY_REGISTERED = -2024 ,   PROPHANDLING_LIST_CANT_ACCESS_DATA = -2025 ,   PROPHANDLING_METHOD_PTR_INVALID = -2026 ,   PROPHANDLING_METHOD_INVALID_PARAM_LIST = -2027 ,   PROPHANDLING_SWIG_ERROR = -2028 ,   PROPHANDLING_INVALID_INPUT_PARAMETER = -2029 ,   PROPHANDLING_COMPONENT_NO_CALLBACK_REGISTERED = -2030 ,   PROPHANDLING_INPUT_BUFFER_TOO_SMALL = -2031 ,   PROPHANDLING_WRONG_PARAM_COUNT = -2032 ,   PROPHANDLING_UNSUPPORTED_OPERATION = -2033 ,   PROPHANDLING_CANT_SERIALIZE_DATA = -2034 ,   PROPHANDLING_INVALID_FILE_CONTENT = -2035 ,   PROPHANDLING_CANT_ALLOCATE_LIST = -2036 ,   PROPHANDLING_CANT_REGISTER_COMPONENT = -2037 ,   PROPHANDLING_PROP_VALIDATION_FAILED = -2038 ,   PROPHANDLING_LAST_VALID_ERROR_CODE = -2099 }
	Error codes of the module handling everything related to properties. More...
enum	TScope {   sGlobal = 0 ,   sUser = 1 }
	Defines the scope for data import/export operations. More...
enum	TStorageFlag {   sfDefault = 0x00000000 ,   sfNative = 0x00000001 ,   sfRaw = 0x00000002 ,   sfVolatile = 0x00000004 ,   sfProcessPropTranslationDict = 0x00000008 ,   sfCreateMissingEntries = 0x00000010 ,   sfProcessReadOnlyComponents = 0x00000020 ,   sfIgnorePropData = 0x00000040 ,   sfProcessDocString = 0x00000080 ,   sfProcessPropConstantsDict = 0x00000100 ,   sfProcessInheritance = 0x00000200 ,   sfIgnoreBasicData = 0x00000400 ,   sfIgnoreInvisible = 0x00000800 ,   sfFile = 0x00001000 ,   sfProcessDisplayName = 0x00002000 ,   sfRAM = 0x4000 ,   sfDontProcessDefault = 0x00020000 ,   sfProcessGenICamSequencerData = 0x00040000 ,   sfProcessGenICamUserSetData = 0x00080000 }
	Defines the way component lists are imported and exported. More...
enum	TStorageLocation {   slNative = 0x1 ,   slNative_Raw = 0x3 ,   slFile = 0x1000 ,   slRAM = 0x4000 }
	Defines valid storage locations for component list import, export and delete operations. More...
enum	TValueType {   vtInt = 0x1 ,   vtFloat ,   vtPtr ,   vtString ,   vtInt64 }
	Allowed values types for property objects. More...

Functions
TPROPHANDLING_ERROR DMR_CALL	OBJ_AttachCallback (HOBJ hObj, CallbackHandle hCallback)
	Attaches a previously created callback to a feature.
TPROPHANDLING_ERROR DMR_CALL	OBJ_CheckHandle (HOBJ hObj, TOBJ_HandleCheckMode mode)
	Checks if a handle to any HOBJ is still valid.
TPROPHANDLING_ERROR DMR_CALL	OBJ_CreateCallback (TCallbackType type, CBOBJChanged pMeth, void *pUserData, CallbackHandle *phCallback)
	Creates a new callback object that can be bound to one or multiple features.
TPROPHANDLING_ERROR DMR_CALL	OBJ_DeleteCallback (CallbackHandle hCallback)
	Deletes a callback object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_DeleteSetting (const char *pName, TStorageFlag storageFlags, TScope scope)
	Tries to delete a certain setting.(deprecated)
TPROPHANDLING_ERROR DMR_CALL	OBJ_DetachCallback (HOBJ hObj, CallbackHandle hCallback)
	Detaches a previously created callback to a feature.
TPROPHANDLING_ERROR DMR_CALL	OBJ_Execute (HOBJ hMeth, const char *pCallParams, const char *pDelimiters, int *pResult)
	Executes the function bound to this method object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_FreeSMemory (char *pBuffer)
	Function to free string memory previously allocated by this module.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetBinary (HOBJ hProp, char *pBuf, unsigned int bufSize, int index)
	Reads binary data from a string property.(deprecated).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetBinaryBufferMaxSize (HOBJ hProp, unsigned int *pBufSize)
	Reads the max size(in bytes) of binary data this property can store.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetBinaryBufferSize (HOBJ hProp, unsigned int *pBufSize, int index)
	Reads the size(in bytes) needed for the binary representation of the string buffer.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetBinaryEx (HOBJ hProp, char *pBuf, unsigned int *pBufSize, int index)
	Reads binary data from a string property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetChangedCounter (HOBJ hProp, unsigned int *pChangedCounter)
	Returns the current changed counter for this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetChangedCounterAttr (HOBJ hProp, unsigned int *pChangedCounter)
	Returns the current changed counter for this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetContentDesc (HOBJ hList, char *pBuf, size_t bufSize)
	Retrieves a string containing information about what's in this list.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetDictSize (HOBJ hProp, unsigned int *pDictSize)
	Receives the size of the property's translation dictionary.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetDisplayName (HOBJ hObj, char *pBuf, size_t bufSize)
	Retrieves the display name of this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetDocString (HOBJ hObj, char *pBuf, size_t bufSize)
	Retrieves a string containing general information about the object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetElementCount (HLIST hList, unsigned int *pElementCount)
	Receives the number of objects stored in a list.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetF (HOBJ hProp, double *pVal, int index)
	Receives a property's value as a float value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFArray (HOBJ hProp, double *pVal, unsigned int valCount, int index)
	Receives one or more values from a property as float values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFDictEntries (HOBJ hProp, char **pTranslationArray, size_t sizePerTranslationBuf, double *pValArray, size_t arraySizes)
	Receives the translation dictionary for a float property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFDictEntry (HOBJ hProp, char *pTranslationString, size_t translationStringBufSize, double *pValue, int index)
	Receives a single translation dictionary entry for a floating point property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFirstChild (HOBJ hObj, HOBJ *phFirstChild)
	Moves to the first child of this object(moves down one level).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFirstSibling (HOBJ hObj, HOBJ *phFirstSibling)
	Moves to the first sibling of this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFlags (HOBJ hObj, TComponentFlag *pFlags)
	Receives the flags associated with this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFlagsS (HOBJ hObj, const char *pSeparator, char *pBuf, size_t bufSize)
	Receives a string representation of the flags associated with this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetFormatString (HOBJ hProp, char *pBuf, size_t bufSize)
	Retrieves the internal format string this property uses to convert data to strings.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetHandle (HLIST hList, const char *pPathAndPropName, HOBJ *phObj)
	Retrieves an objects handle(deprecated).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetHandleEx (HLIST hList, const char *pObjName, HOBJ *phObj, unsigned int searchMode, int maxSearchDepth)
	Retrieves an objects handle.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetI (HOBJ hProp, int *pVal, int index)
	Receives a property's value as an integer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetI64 (HOBJ hProp, int64_type *pVal, int index)
	Receives a property's value as an integer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetI64Array (HOBJ hProp, int64_type *pVal, unsigned int valCount, int index)
	Receives one or more values from a property as 64 bit integer values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetI64DictEntries (HOBJ hProp, char **pTranslationArray, size_t sizePerTranslationBuf, int64_type *pValArray, size_t arraySizes)
	Receives the translation dictionary for an integer property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetI64DictEntry (HOBJ hProp, char *pTranslationString, size_t translationStringBufSize, int64_type *pValue, int index)
	Receives a single translation dictionary entry for a 64 bit integer property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetIArray (HOBJ hProp, int *pVal, unsigned int valCount, int index)
	Receives one or more values from a property as integer values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetIDictEntries (HOBJ hProp, char **pTranslationArray, size_t sizePerTranslationBuf, int *pValArray, size_t arraySizes)
	Receives the translation dictionary for an integer property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetIDictEntry (HOBJ hProp, char *pTranslationString, size_t translationStringBufSize, int *pValue, int index)
	Receives a single translation dictionary entry for an integer property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetLastSibling (HOBJ hObj, HOBJ *phLastSibling)
	Moves to the last sibling in the current list.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetMaxValCount (HOBJ hProp, unsigned int *pValCount)
	Receives the maximum number of values this property can store.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetName (HOBJ hObj, char *pBuf, size_t bufSize)
	Retrieves the name of this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetNextSibling (HOBJ hObj, HOBJ *phNextSibling)
	Moves to the next sibling of this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetP (HOBJ hProp, void **pVal, int index)
	Receives a property's value as a pointer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetParent (HOBJ hObj, HOBJ *phParent)
	Moves to the parent object(moves up one level).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetRepresentation (HOBJ hObj, TComponentRepresentation *pRepresentation)
	Receives the recommended representation associated with this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetRepresentationS (HOBJ hObj, char *pBuf, size_t bufSize)
	Receives a string representation of the recommended representation of the referenced object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetS (HOBJ hProp, char *pVal, size_t bufSize, int index)
	Receives a property's value as a string.
MVDMR_API TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSArrayFormatted (HOBJ hProp, char *pBuf, size_t bufSize, const char *pFormat, const char *pDelimiters, int startIndex, int endIndex, int mode)
	Receives a set of values stored by the property(deprecated).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSArrayFormattedEx (HOBJ hProp, char *pBuf, size_t *pBufSize, const char *pFormat, const char *pDelimiters, int startIndex, int endIndex, int mode)
	Receives a set of values stored by the property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSelectedFeatures (HOBJ hObj, int index, HOBJ *phFeatures, size_t *pFeatureCount)
	Retrieves the list of object handles of objects that are selected by this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSelectingFeatures (HOBJ hObj, int index, HOBJ *phFeatures, size_t *pFeatureCount)
	Retrieves the list of object handles of objects that are selecting this object.
MVDMR_API TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSFormatted (HOBJ hProp, char *pBuf, size_t bufSize, const char *pFormat, int index)
	Receives a property's value as a formatted string(deprecated).
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSFormattedEx (HOBJ hProp, char *pBuf, size_t *pBufSize, const char *pFormat, int index)
	Receives a property's value as a formatted string.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSParamList (HOBJ hMeth, char *pBuf, size_t bufSize)
	Receives a string representation of a methods parameter list.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetSWithInplaceConstruction (HOBJ hObj, TOBJ_StringQuery sq, char **pResult, SCF pConstructionFunc, int, int reserved)
	A more sophisticated and efficient way to read string values from this module.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetType (HOBJ hObj, TComponentType *pType)
	Receives the type of the referenced object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetTypeS (HOBJ hObj, char *pBuf, size_t bufSize)
	Receives a string representation of the type of the referenced object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetValCount (HOBJ hProp, unsigned int *pValCount)
	Receives the current number of values stored by the property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetVisibility (HOBJ hObj, TComponentVisibility *pVisibility)
	Receives the recommended visibility associated with this object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_GetVisibilityS (HOBJ hObj, char *pBuf, size_t bufSize)
	Receives a string representation of the recommended visibility of the referenced object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_IsConstantDefined (HOBJ hProp, int constant, unsigned int *pResult)
	Checks if a certain constant for this property is defined.
TPROPHANDLING_ERROR DMR_CALL	OBJ_IsDefault (HOBJ hObj, unsigned int *pResult)
	Checks if the object is set to its default value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_IsSettingAvailable (const char *pName, TStorageFlag storageFlags, TScope scope)
	Checks if a certain setting is available.(deprecated)
TPROPHANDLING_ERROR DMR_CALL	OBJ_RemoveVal (HOBJ hProp, int index)
	Removes a certain value from a property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_RepresentationToString (TComponentRepresentation representation, char *pBuf, size_t bufSize)
	Receives a string representation of a component representation passed to the function.
TPROPHANDLING_ERROR DMR_CALL	OBJ_RestoreDefault (HOBJ hObj)
	Restores the default for the referenced object.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetBinary (HOBJ hProp, const char *pBuf, unsigned int bufSize, int index)
	Writes binary data to a string property.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetF (HOBJ hProp, double val, int index)
	Sets a property's value as a float value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetFArray (HOBJ hProp, const double *pVal, unsigned int valCount, int index)
	Sets one or more values from a property as float values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetI (HOBJ hProp, int val, int index)
	Sets a property's value as an integer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetI64 (HOBJ hProp, int64_type val, int index)
	Sets a property's value as a 64 bit integer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetI64Array (HOBJ hProp, const int64_type *pVal, unsigned int valCount, int index)
	Sets one or more values from a property as 64 bit integer values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetIArray (HOBJ hProp, const int *pVal, unsigned int valCount, int index)
	Sets one or more values from a property as integer values.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetP (HOBJ hProp, void *val, int index)
	Sets a property's value as a pointer value.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetS (HOBJ hProp, const char *pVal, int index)
	Sets a property by string.
TPROPHANDLING_ERROR DMR_CALL	OBJ_SetValCount (HOBJ hProp, unsigned int valCount)
	Resizes the property's data array.
TPROPHANDLING_ERROR DMR_CALL	OBJ_VisibilityToString (TComponentVisibility visibility, char *pBuf, size_t bufSize)
	Receives a string representation of a component visibility passed to the function.

Variables
const unsigned int	DEFAULT_STRING_SIZE_LIMIT = 8192
	Defines a default length for a string buffer.
const int	END_OF_LIST = -1
	A constant defining that property values will be read from an array property until the last value.
const int	INVALID_ID = -1
	A constant to check for an invalid ID returned from the property handling module.
const int	PROP_MAX_VAL = -1
	The index value to query the maximum value defined for this property.
const int	PROP_MIN_VAL = -2
	The index value to query the minimum value defined for this property.
const int	PROP_STEP_WIDTH = -3
	The index value to query the step width value defined for this property.
const int	ROOT_LIST = 0
	A constant defining the unique identifier for the root component list containing all other lists.
const unsigned int	smIgnoreLists = 0x2
	When set lists are not taken into account during a search.
const unsigned int	smIgnoreMethods = 0x4
	When set method objects are not taken into account during a search.
const unsigned int	smIgnoreProperties = 0x8
	When set property objects are not taken into account during a search.

Detailed Description

Functions for accessing properties, methods and lists.

Typedef Documentation

CallbackHandle

typedef void* CallbackHandle

A type to create a unique identifier for a callback.

Since

1.12.18

Enumeration Type Documentation

TCallbackType

enum TCallbackType

Defines the type of callback to register.

Enumerator
ctOnChanged	Execute callback whenever this component has been modified.
ctOnReadData	Executed when a property's value is read. The callback is executed before the value is returned to the user. This allows i.e. a driver to determine the value for this property only if the user is interested in its data.
ctOnWriteData	Executed when a property's value is written. The callback is executed before the value is actually assigned. This allows i.e. a driver to validate if this is a valid value for the property.
ctOnRefreshCache	Executed when a component is accessed (read or write) and some of the internal data needs to be refreshed from an external source. The callback is executed before the component data is accessed. This allows i.e. a driver to update the data before.

TComponentFlag

enum TComponentFlag

Flags defining access rights and other component properties.

Flags defining access rights and other component properties

Enumerator
cfUndefined	This is used to define an inconsistent/invalid flag. This e.g. can be used as a return value for a function, that could not calculate a valid flag mask.
cfReadAccess	This component can be accessed for reading. If this flag is set this component can be accessed for reading. This involves reading a property's data, reading a component list's elements reading the size of a component list and so on.
cfWriteAccess	This component can be accessed for writing. If this flag is set this component can be accessed for writing or modifying its data. This involves writing values to a property, adding components to a list and so on.
cfRWAccess	This component can be accessed for both reading and writing. This just combines cfReadAccess and cfWriteAccess
cfFixedSize	This components element count can be modified. If this flag is set this components element count can't be modified. For a list this would mean, that the number of elements stored in this list can't be modified. For a property this means, that the number of values stored in the property can't be modified.
cfInvisible	The component is shadowed by other settings currently if set. This flag is used to specify that this component currently has no effect on the behaviour of the system. This flag is just meant as a hint for the user. The property module itself does NOT use this flag for anything.
cfAllowValueCombinations	Allows combinations of translation dictionary entry as valid values. If this flag is set for a property that defines a translation dictionary not only values, which are registered in the translation dictionary are allowed values for this property, but also values logical OR-ed together with values from the translation dictionary (these obviously can't be set as strings). A property defines two entries ("one", 1) and ("two", 2) then 1 | 2 = 3 will be a valid value as well, but "three" obviously won't. In a GUI application a property specifying this flag should be displayed as a set of check-box controls (one for each dictionary entry) or something similar. Note If this flag is specified for a component, which is not a property, it will have no effect on the behaviour of the component. Only integer properties can use this feature
cfShouldBeDisplayedAsList	Informs a displaying GUI that this component should be displayed as a list. This flag e.g. can be set for an array property to inform a displaying GUI, that this property is best displayed as a list with a entry for each element. This flag is just meant as a hint for the user. The property module itself does NOT use this flag for anything.
cfDisallowSerialize	If set this component or derived components can't be stored as external data.
cfAlwaysForceClone	If set this component is always cloned completely. This results in the component being completely independent from its parent no matter whether it has been built while deriving or cloning a list and thus the components within this list and its sub-lists. This will change the behaviour to that effect that changing the parent component will no longer affect the 'derived' component. So different default values, constants and translation dictionaries for properties within an inheritance hierarchy can be defined. Note This feature is currently only supported for components of type ctPropInt, ctPropInt64 and ctPropFloat.
cfNotAvailable	If set, this component is currently not available due to the setting of another feature. In this case this feature can't be written to nor can it be read.
cfNotImplemented	If set, this feature has been defined, but so far has not been implemented.
cfContainsBinaryData	Specifies a property, which contains binary data. This flag is used to specify a property that contains data in binary format
cfShouldBeDisplayedAsEnumeration	Informs a displaying GUI that this component should be displayed as an enumeration(e.g. with a combo box). This flag e.g. can be set for a property to inform a displaying GUI, that this property is best displayed as a combo box or something similar. This flag is just meant as a hint for the user. The property module itself does NOT use this flag for anything. Since 1.12.57
cfAlwaysForceUpdate	This feature will ALWAYS execute internal update callbacks and will treat each write attempt to this feature as a value different from the current one. Since 2.0.11

TComponentRepresentation

enum TComponentRepresentation

Defines valid recommended representations for features.

These representations can be used to create a suitable GUI editor for a features.

Since

2.14.0

Enumerator
crUndefined
crLinear	Defines a feature with linear behaviour. One possible editor would be a slider with linear behaviour.
crLogarithmic	Defines a feature with logarithmic behaviour. One possible editor would be a slider with logarithmic behaviour.
crBoolean	Defines a boolean feature. This could be displayed to the user as a check box.
crPureNumber	Defines a feature representing a pure number. This could be displayed to the user as an edit control.
crHexNumber	Defines a feature representing a hexadecimal number.
crIPv4Address	Defines a feature representing an IPv4 address. This could be displayed to the user as a custom IPv4 edit control.
crMACAddress	Defines a feature representing a MAC address. This could be displayed to the user as a custom MAC address edit control.
crFileName	Defines a feature representing a file name. This could be displayed to the user as a file selection dialog.
crDirectoryName	Defines a feature representing a directory name. This could be displayed to the user as a directory selection dialog.

TComponentType

enum TComponentType

Allowed components handled by this module.

This module can handle the types listed in this enumeration only.

Enumerator
ctProp	A property type. This type will never occur in a real world application. It's just used to build up the other types. Properties can be used to store user specific data in a structured way.
ctList	A list object. Lists can contain other components like lists, methods and properties. Thus lists can be used to build up hierarchical structures of different components.
ctMeth	A method object. Method objects provide the possibility to organize functions in lists.
ctPropInt	Defines a property for 32 bit integer values.
ctPropFloat	Defines a property for floating point values.
ctPropString	Defines a property for string values.
ctPropPtr	Defines a property for pointer values.
ctPropInt64	Defines a property for 64 bit integer values.

TComponentVisibility

enum TComponentVisibility

Defines valid recommended visibilities for features.

These visibilities can be used to create GUIs in which the user can select the amount of features he wants to access.

Enumerator
cvBeginner	Defines a feature that should be visible for all users via the GUI and API. This is the default visibility if no visibility has been specified for a particular component.
cvExpert	Defines a feature that requires a more in-depth knowledge of the functionality. This is the preferred visibility level for all advanced features.
cvGuru	Defines an advanced feature that if not configured correctly might result in unexpected behaviour.
cvInvisible	Defines a feature that should not be displayed in a GUI but is still accessible via API function calls.

TPROPHANDLING_ERROR

enum TPROPHANDLING_ERROR

Error codes of the module handling everything related to properties.

Enumerator
PROPHANDLING_NO_ERROR	The operation has been executed successfully.
PROPHANDLING_NOT_A_LIST	This component is not a list. A list operation for this component has been called but this component does not reference a list.
PROPHANDLING_NOT_A_PROPERTY	This component is not a property. A property operation for this component has been called but this component does not reference a property.
PROPHANDLING_NOT_A_METHOD	This component is not a method. A method operation for this component has been called but this component does not reference a method.
PROPHANDLING_NO_READ_RIGHTS	The caller has no read rights for this component. It has been tried to read data from this component, but the caller has no read rights for this component.
PROPHANDLING_NO_WRITE_RIGHTS	The caller has no write rights for this component. It has been tried to modify data of this component, but the caller has no write rights for this component.
PROPHANDLING_NO_MODIFY_SIZE_RIGHTS	The caller can't modify the size of this component. It has been tried to modify the size of this list or the number of values stored by a property, but the caller doesn't have the required right to do this. This error will also be reported if the user tried to increase the number of values handled by a property above the maximum number of values it can handle. Therefore before resizing a property check if the new size might exceeds this maximum value by calling the appropriate function.
PROPHANDLING_INCOMPATIBLE_COMPONENTS	The two involved components are not compatible. An operation requiring two compatible components has been called with two components, which are not compatible.
PROPHANDLING_UNSUPPORTED_PARAMETER	One or more of the specified parameters are not supported by the function. This error might also be generated if a certain feature is not available on the current platform.
PROPHANDLING_SIZE_MISMATCH	Different sized value buffers have been passed. While trying to read value pairs the caller passed two different sized value buffers to a function while one is too small to hold all the information.
PROPHANDLING_IMPLEMENTATION_MISSING	A feature that is not implemented so far has been requested. The caller requested a feature, that hasn't been implemented so far. This error code is only provided for compatibility and will be set in very rare cases only.
PROPHANDLING_ACCESSTOKEN_CREATION_FAILED	An access token object couldn't be created. This can either happen, because the caller has not the rights required to create an access token or because the system runs very low on memory. Deprecated: This error code currently is not used anywhere within this framework. It might be removed in a future version.
PROPHANDLING_INVALID_PROP_VALUE	It has been tried to assign an invalid value to a property. This can either happen if the value lies above or below the min. or max. value for a property or when it has been tried to write a value to a property, which is not in the properties translation dictionary (if it defines one). To find out, which values are allowed for the property in question the user should • Check if the property defines a translation dictionary. • Check the allowed values within a translation dictionary if one is defined. • Check the min and max value for properties, that define limits.
PROPHANDLING_PROP_TRANSLATION_TABLE_CORRUPTED	The properties translation table has been corrupted. The properties translation table has been corrupted for an unknown reason and can't be used anymore.
PROPHANDLING_PROP_VAL_ID_OUT_OF_BOUNDS	Invalid value index. The caller tried to read a value from an invalid index from a property. Most properties store one value only, thus the only valid positive value index will be 0 (some negative index values are reserved for special values like e.g. the min/max value of a property). However some properties might store more than one value, thus the max. allowed index might be higher. The highest index allowed will always be the value count of a property minus one for properties with the cfFixedSize flag set. Other properties will automatically adjust the size once the user writes to an index out of bounds.
PROPHANDLING_PROP_TRANSLATION_TABLE_NOT_DEFINED	This property doesn't define a translation table. The caller tried to modify a translation table, that hasn't been defined for this property.
PROPHANDLING_INVALID_PROP_VALUE_TYPE	An invalid value has been passed to the property. Although properties are quite tolerant regarding the allowed assignment for them some value types can't be used to write all properties. As an example assigning a float value to an integer property would result in this error. Another reason for this error might be when a user tried to access e.g. a float property with functions meant to be used for int properties.
PROPHANDLING_PROP_VAL_TOO_LARGE	A too large value has been passed. One or more of the values the caller tried to write to the property are larger than the max. allowed value for this property.
PROPHANDLING_PROP_VAL_TOO_SMALL	A too small value has been passed. One or more of the values the caller tried to write to the property are smaller than the min. allowed value for this property.
PROPHANDLING_COMPONENT_NOT_FOUND	The specified component could not be found.
PROPHANDLING_LIST_ID_INVALID	An invalid list has been referenced.
PROPHANDLING_COMPONENT_ID_INVALID	An invalid component within a list has been referenced.
PROPHANDLING_LIST_ENTRY_OCCUPIED	The specified list index is occupied. During the creation of a new component the caller tried the insert the newly created component into a list at a position already used to store another component.
PROPHANDLING_COMPONENT_HAS_OWNER_ALREADY	The specified component already has an owner. The caller tried to assign an owner to a component that already has an owner. An owner once defined can't be modified anymore.
PROPHANDLING_COMPONENT_ALREADY_REGISTERED	It has been tried to register the same component at twice in the same list.
PROPHANDLING_LIST_CANT_ACCESS_DATA	The desired data can't be accessed or found. During loading or saving data this error can occur e.g. if it has been tried to import a setting from a location where the desired setting couldn't be found. Another reason for this error might be that the current user is not allowed to perform a certain operation on the desired data (e.g. a user tries to delete a setting that is stored with global scope but does not have elevated access rights).
PROPHANDLING_METHOD_PTR_INVALID	The function pointer of the referenced method object is invalid.
PROPHANDLING_METHOD_INVALID_PARAM_LIST	A method object has an invalid parameter list.
PROPHANDLING_SWIG_ERROR	This indicates an internal error occurred within the SWIG generated wrapper code, when working under Python.
PROPHANDLING_INVALID_INPUT_PARAMETER	A invalid input parameter has been passed to a function of this module. In most cases this might be a unassigned pointer, where a valid pointer to a user defined storage location was expected.
PROPHANDLING_COMPONENT_NO_CALLBACK_REGISTERED	The user tried to modify a registered callback, but no callback has been registered for this component.
PROPHANDLING_INPUT_BUFFER_TOO_SMALL	The user tried to read data into a user supplied storage location, but the buffer was too small to accommodate the result.
PROPHANDLING_WRONG_PARAM_COUNT	The number of parameters is incorrect. This error might occur if the user called a function with a variable number of input or output parameters and the number of parameters passed to the function does not match the number of required parameters.
PROPHANDLING_UNSUPPORTED_OPERATION	The user tried to execute an operation, which is not supported by the component he is referring to.
PROPHANDLING_CANT_SERIALIZE_DATA	The user tried to save(serialize) a property list without having the right to do this.
PROPHANDLING_INVALID_FILE_CONTENT	The user tried to use a file to update or create a component list, that does not contain valid data for this operation. This e.g. might happen, if the file does not contain valid XML data or XML data that is not well formed.
PROPHANDLING_CANT_ALLOCATE_LIST	This error will occur when the modules internal representation of the tree structure does not allow the allocation of a new list. In this case either new list can't be allocated. The only way to solve this problem is to delete another list.
PROPHANDLING_CANT_REGISTER_COMPONENT	The referenced list has no space left to register this component at the desired position. There might however be an empty space within the list where this element could be registered, but no more components can be registered at the end of this list.
PROPHANDLING_PROP_VALIDATION_FAILED	The user tried to assign a value to a property, that is invalid. This will result in a detailed error message in the log-file. This error might arise e.g. when a string property doesn't allow the string to contain numbers. In this case trying to set the properties value to 'blabla7bla' would cause this error.
PROPHANDLING_LAST_VALID_ERROR_CODE	Defines the last valid error code value for the property module.

TScope

enum TScope

Defines the scope for data import/export operations.

Enumerator
sGlobal	Save the setting as global as possible.
sUser	Save the setting in a user specific location.

TStorageFlag

enum TStorageFlag

Defines the way component lists are imported and exported.

Component lists can be imported and exported from/to XML files and (under Windows©) from/into the Registry. These flags define how this is done.

Enumerator
sfDefault	A dummy flag to specify the default behaviour. Store/load operations will done in XML format in this case.
sfNative	Stores/loads the setting in/from a platform dependent location. Under Windows© the Registry will be used to as a platform dependent location, while under other platforms an XML file will be processed in the path specified as the settings name. Note Please note, that using this flag will introduce platform dependency. E.g. specifying this flag under Linux will process XML data, while under Windows© the Registry will be used. This is why A call to a load function with this flag with the corresponding XML file in the applications directory might succeed under Linux while it fails under Windows©.
sfRaw	Stores/loads the setting in raw mode. Note Under Windows© this mode only works in connection with the sfNative flag. In that case an arbitrary hive from the registry can be used to create a tree of lists and properties. This only makes sense for very special applications and therefore is not needed to write applications, that load and store current settings.
sfVolatile	Stores lists volatile. under Windows© when the sfNative flag is set this will store the component list as a volatile key in the Registry. This means that the data will remain in the Registry until the system is shut down.
sfProcessPropTranslationDict	If set properties translation dictionaries will be processed for this import/export operation. This option forces the function to process the translation dictionaries, which might be assigned to properties.
sfCreateMissingEntries	If set ALL entries in the store data will be created. When loading a setting not only the current lists data will be updated, but also properties, lists or data, which is found in the storage location but not in the setting to update will be added to the setting as well.
sfProcessReadOnlyComponents	If set read-only components will be processed for this import/export operation. When importing, exporting or updating a component list components with the cfWriteAccess not set will be ignored.
sfIgnorePropData	If set data for properties will no be updated. If this flag is set the values stored by the property will be ignored for this import/export operation. Note This flag is ignored, if sfNative is specified.
sfProcessDocString	If set the documentation string will be processed. If this flag is set the documentation string will be processed for this import/export operation. Note This flag is ignored, if sfNative is specified.
sfProcessPropConstantsDict	If set the defined constants for properties will be processed. If this flag is set the defined constants for properties will be processed for this import/export operation.
sfProcessInheritance	If set the lists inheritance relationship will be processed. If this flag is set the inheritance relationship between lists will be processed for the current import/export operation. Note Limitations: derived lists must appear in a list after the parent list. So if a list is derived from another list, it has to be registered with a higher index either in the same list as the parent or in a list with a higher index then the list holding the parent in a top level list. Example for a legal structure: A |-B | |-parent | |-child |-C | |-child |-child Example for illegal structures: A |-child |-parent or A |-B | |-child |-parent this feature is not available when sfNative is specified.
sfIgnoreBasicData	Specifies if basic data shall be processed. For e.g. settings it's not necessary to import/export information about the value type for properties or the size of lists etc. as this information is available internally anyway. So interface functions dealing with settings should specify this flag in any case.
sfIgnoreInvisible	Specifies if invisible components shall be processed. When invisible data doesn't need to be processed this flag can be specified. Invisible components do not influence the current systems behaviour. Note This feature is currently only supported for output operations and is ignored for input operations.
sfFile	Stores/loads the setting in/from an XML file. If this flag is specified the data will be imported/exported from/to an XML file.
sfProcessDisplayName	If set the display name will be processed. If this flag is set the display name will be processed for this import/export operation. Note This flag is ignored, if sfNative is specified.
sfRAM	Stores/loads the setting in/from RAM file. If this flag is specified the data will be imported/exported from/to RAM. Data stored this way should be freed when no longer needed to avoid a waste of memory. However when shutting down Impact Acquire completely (e.g. when unloading the mvPropHandling library from memory all memory allocated by settings stored this way will be freed automatically). Note This flag must not be combined with sfNative or sfFile. Since 2.19.0
sfDontProcessDefault	Specifies if the 'is-default' flag for components shall be ignored during import/export operations. If this flag is set the 'is-default' flag will not be processed during this import/export operation. Note This flag is ignored, if sfNative is specified.
sfProcessGenICamSequencerData	Processes GenICam sequencer set related data during a storage operation. Note This flag will affect devices operated in GenICam interface layout only! Attention Settings stored this way cannot be loaded on systems running Impact Acquire versions smaller than 2.28.0. Since 2.28.0
sfProcessGenICamUserSetData	Processes GenICam user set related data during a storage operation. Note This flag will affect devices operated in GenICam interface layout only! Attention Settings stored this way cannot be loaded on systems running Impact Acquire versions smaller than 2.28.0. Since 2.28.0

TStorageLocation

enum TStorageLocation

Defines valid storage locations for component list import, export and delete operations.

Component lists can be imported and exported from/to XML files, process RAM and (under Windows©) from/into the Registry.

Since

2.19.0

Enumerator
slNative	Stores/loads the setting in/from a platform dependent location. Under Windows© the Registry will be used to as a platform dependent location, while under other platforms an XML file will be processed in the path specified as the settings name. Note Please note, that using this mode will introduce platform dependency. E.g. specifying this mode under Linux will process XML data, while under Windows© the Registry will be used. This is why A call to a load function with this mode with the corresponding XML file in the applications directory might succeed under Linux while it fails under Windows©.
slNative_Raw	Stores/loads the setting in/from a platform dependent location. Under Windows© the Registry will be used to as a platform dependent location, while under other platforms an XML file will be processed in the path specified as the settings name. Note Please note, that using this mode will introduce platform dependency. E.g. specifying this mode under Linux will process XML data, while under Windows© the Registry will be used. This is why A call to a load function with this mode with the corresponding XML file in the applications directory might succeed under Linux while it fails under Windows©. Under Windows© with this mode an arbitrary hive from the registry can be used to create a tree of lists and properties. This only makes sense for very special applications and therefore is not needed to write applications, that load and store current settings.
slFile	Stores/loads the setting in/from an XML file. Setting data will be imported/exported from/to an XML file.
slRAM	Stores/loads the setting in/from RAM file. Setting data will be stored in the RAM of the current process. Data stored this way should be freed when no longer needed to avoid a waste of memory. However when shutting down Impact Acquire completely (e.g. when unloading the mvPropHandling library from memory all memory allocated by settings stored this way will be freed automatically).

TValueType

enum TValueType

Allowed values types for property objects.

Enumerator
vtInt	Defines a property for 32 bit integer types.
vtFloat	Defines a property for float types.
vtPtr	Defines a property for pointer types.
vtString	Defines a property for strings.
vtInt64	Defines a property for 64 bit integer types.

Function Documentation

OBJ_AttachCallback()

TPROPHANDLING_ERROR DMR_CALL OBJ_AttachCallback	(	HOBJ	hObj,
		CallbackHandle	hCallback )

Attaches a previously created callback to a feature.

Once a callback has been attached whenever a feature changes the attached callback will be executed.

See also

OBJ_CreateCallback(),
OBJ_DeleteCallback(),
OBJ_DetachCallback()

Since

1.12.18

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the feature the callback shall be attached to.
[in]	hCallback	A valid handle to a callback object previously created using OBJ_CreateCallback().

OBJ_CheckHandle()

TPROPHANDLING_ERROR DMR_CALL OBJ_CheckHandle	(	HOBJ	hObj,
		TOBJ_HandleCheckMode	mode )

Checks if a handle to any HOBJ is still valid.

This function can be used to check if hObj references a valid object. HOBJ handles once valid e.g. might become invalid when a device driver has been closed in the meantime or if an object resides in a list deleted by the user(e.g. by calling the function DMR_DeleteList().

Returns

• PROPHANDLING_NO_ERROR if successful and the handle is valid with respect to the specified check mode.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to check.
[in]	mode	Specifies what/how to check this handle

OBJ_CreateCallback()

TPROPHANDLING_ERROR DMR_CALL OBJ_CreateCallback	(	TCallbackType	type,
		CBOBJChanged	pMeth,
		void *	pUserData,
		CallbackHandle *	phCallback )

Creates a new callback object that can be bound to one or multiple features.

Calling this function creates a new callback object that can be bound to one or multiple features. This mechanism can be used to e.g. get informed whenever a certain property has changed its value or visibility.

Callback objects once created can be attached to multiple features. Which feature actually did cause the callback will be part of the information provided inside the callback.

Note

Please note that the callback function will be executed within the thread context that is causing the callback, thus by any thread belonging to the internal device driver instance. There is a high chance that this is a different thread than any known to by the application, thus appropriate mechanisms to ensure correct execution must be implemented by an application(e.g. GUI applications might send an event to the main thread instead of directly accessing GUI elements from here).

As each device driver instance internally creates multiple threads and since components can be modified by the driver framework from any of these threads, the thread context might in fact be different each time this function gets called. Accessing data from properties, lists or methods exposed by this API is thread safe so e.g. property values can be read out in parallel securely! However the callback in a worst case (when several components have been registered to a single callback) might in fact be called in parallel so everything that happens in here should be designed accordingly!

Attention

It is NOT recommended to do time consuming stuff here! This function should be considered as something like an interrupt instead: Just take a note about what did just happen and leave. The calling thread will block until this function does return which might have all sorts of consequences if this takes a lot of time. In the worst case e.g. image data might get lost!

GenICam event specific: When dealing with GenICam device events from a single device only within this callback due to the internal design it is guaranteed that this callback will NOT be executed in parallel since the device events will be received sequentially and will always be reported by the same (device driver instance related) thread! So when e.g. registering for changes to the following properties:

• EventLine4RisingEdgeTimestamp
• EventLine5RisingEdgeTimestamp
• EventExposureEndTimestamp for a single device only then the following things are guaranteed:
• The thread context used by the function referenced by pMeth will always be the same until the device is either closed or the connection is lost e.g. due to a reboot
• The function referenced by pMeth will NOT be called concurrently
• The event property changes will be reported in the same order as generated by the device

See also

OBJ_DeleteCallback(),
OBJ_AttachCallback(),
OBJ_DetachCallback()

Since

1.12.18

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	type	The type of callback that shall be registered
[in]	pMeth	A pointer to the callback function that shall be executed whenever callback conditions are met.
[in]	pUserData	A pointer to user specific data bound to this callback. This data will be passed back to the user whenever the callback function gets executed and can be used to attach custom data to the callback function.
[out]	phCallback	A pointer to the variable retrieving a handle to the internal callback object created on a successful call.

OBJ_DeleteCallback()

TPROPHANDLING_ERROR DMR_CALL OBJ_DeleteCallback

(

CallbackHandle

hCallback

)

Deletes a callback object.

Calling this function deletes a callback object previously created using OBJ_DeleteCallback().

Attention

An application must ensure that all features this callback has been attached to must be detached from the callback before! Not doing so will result in a crash whenever the next feature still attached to this callback is modified!

See also

OBJ_CreateCallback(),
OBJ_AttachCallback(),
OBJ_DetachCallback()

Since

1.12.18

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]

hCallback

A valid handle to a callback object previously created using OBJ_CreateCallback().

OBJ_DeleteSetting()

TPROPHANDLING_ERROR DMR_CALL OBJ_DeleteSetting	(	const char *	pName,
		TStorageFlag	storageFlags,
		TScope	scope )

Tries to delete a certain setting.(deprecated)

Deprecated

This function has been declared deprecated and might be removed in future versions of this interface. Use OBJ_DeleteSetting() instead.

Please note that certain user privileges might be required to delete a global setting.

Returns

• PROPHANDLING_NO_ERROR if the setting could be deleted.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	pName	The name of the setting to look for.
[in]	storageFlags	The flags which define which information shall be read from the location and how this information shall be interpreted. This parameter MUST be set to one of the following values: sfNative sfFile sfRAM
[in]	scope	Specifies where to look for the setting.

OBJ_DetachCallback()

TPROPHANDLING_ERROR DMR_CALL OBJ_DetachCallback	(	HOBJ	hObj,
		CallbackHandle	hCallback )

Detaches a previously created callback to a feature.

Afterwards changes to the feature referenced by hObj will no longer result in the callback referenced by hCallback being executed.

See also

OBJ_CreateCallback(),
OBJ_DeleteCallback(),
OBJ_AttachCallback()

Since

1.12.18

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the feature the callback shall be detached from.
[in]	hCallback	A valid handle to a callback object previously created using OBJ_CreateCallback().

OBJ_Execute()

TPROPHANDLING_ERROR DMR_CALL OBJ_Execute	(	HOBJ	hMeth,
		const char *	pCallParams,
		const char *	pDelimiters,
		int *	pResult )

Executes the function bound to this method object.

This is a method related function and it will fail if this object does not reference an object of type ctMeth.

This function can be used to call any function whose handle is known To call a function successfully the parameters passed to the function must match the parameters expected by the function.

All parameters are passed as a single string, which is parsed with respect to the given delimiter characters internally.

To find out which kind of parameters are expected by the function use the function OBJ_GetSParamList().

floating point values can be passed either with a '.' or a ',' acting as the decimal point.

'empty' strings can be passed as a single underline('_').

Attention

The characters '.', ',' and '_' can't be used as delimiters.

EXAMPLES:

// call a function expecting a string and a float value parameters separated by spaces
int result;
OBJ_Execute( hMeth, "stringParam 3,14", " ", &result );
// call of a function expecting 2 integers an a string where an empty string shall be passed
// parameters are separated by '%'
OBJ_Execute( hMeth, "1000%666%_", "%", &result );

See also

OBJ_GetSParamList(),
OBJ_GetType()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hMeth	A handle to the method.
[in]	pCallParams	A '\0' terminated string containing the parameters to pass to the function. pCallParams can be 0 if the function does not expect any parameters
[in]	pDelimiters	A '\0' terminated string containing the delimiter for the parameter list. pDelimiters can be 0 if pCallParams is 0 as well.
[out]	pResult	A pointer to an integer variable that will contain the return value of the method after the call if this method returns a value.

OBJ_FreeSMemory()

TPROPHANDLING_ERROR DMR_CALL OBJ_FreeSMemory

(

char *

pBuffer

)

Function to free string memory previously allocated by this module.

Parameters

[in]

pBuffer

A pointer to a buffer previously allocated by this module.

OBJ_GetBinary()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetBinary	(	HOBJ	hProp,
		char *	pBuf,
		unsigned int	bufSize,
		int	index )

Reads binary data from a string property.(deprecated).

Deprecated

This function has been declared deprecated. Use OBJ_GetBinaryEx() instead.

This is a string property related function and it will fail if this object does not specify the ctPropString flag(s).

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

Binary data can only be stored in string properties. When writing binary data to a string property it is stored in Base64 format internally. The Base64 algorithm converts arbitrary data into a readable and printable string representation. As a result of this 3 bytes of arbitrary binary data will occupy 4 bytes of memory.

Reading binary data with this function obviously only makes sense if the property has been assigned the value by a previous call to OBJ_SetBinary(). However using this method any kind of data can be stored by a string property. This can e.g. be interesting when certain data shall be stored in the user accessible part of the devices non-volatile memory.

See also

OBJ_SetBinary(),
OBJ_GetBinaryBufferSize(),
OBJ_GetBinaryBufferMaxSize()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the string property. If this handle does not reference a string property, this function will fail and return an error.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's binary representation of the value.
[in]	bufSize	The size of the user supplied buffer. To find out how much memory must be allocated to store the binary representation of the string property's data the function OBJ_GetBinaryBufferSize() should be called.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetBinaryBufferMaxSize()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetBinaryBufferMaxSize	(	HOBJ	hProp,
		unsigned int *	pBufSize )

Reads the max size(in bytes) of binary data this property can store.

This is a string property related function and it will fail if this object does not specify the ctPropString flag(s).

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

When binary data shall be stored in a string property, the user will need to allocate memory when this data shall be written to the property. To find out how much binary data can be stored by a property before calling the function OBJ_SetBinary() this function can be used.

See also

OBJ_GetBinaryEx(),
OBJ_SetBinary(),
OBJ_GetBinaryBufferMaxSize()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the string property. If this handle does not reference a string property, this function will fail and return an error.
[out]	pBufSize	A pointer to the variable that will receive the max size of the binary buffer this property can store in bytes.

OBJ_GetBinaryBufferSize()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetBinaryBufferSize	(	HOBJ	hProp,
		unsigned int *	pBufSize,
		int	index )

Reads the size(in bytes) needed for the binary representation of the string buffer.

This is a string property related function and it will fail if this object does not specify the ctPropString flag(s).

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

When binary data has been stored in a string property, the user will need to allocate memory when this data shall be read back from the user. To find out how much memory needs to be allocated and then passed to the function OBJ_GetBinaryEx() this function can be used.

See also

OBJ_GetBinaryEx(),
OBJ_SetBinary(),
OBJ_GetBinaryBufferMaxSize()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the string property. If this handle does not reference a string property, this function will fail and return an error.
[out]	pBufSize	A pointer to the variable that will receive the size of the needed buffer.
[in]	index	The index of the value for which to query the buffer size(if this property holds more than one value).

OBJ_GetBinaryEx()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetBinaryEx	(	HOBJ	hProp,
		char *	pBuf,
		unsigned int *	pBufSize,
		int	index )

Reads binary data from a string property.

This is a string property related function and it will fail if this object does not specify the ctPropString flag(s).

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

Binary data can only be stored in string properties. When writing binary data to a string property it is stored in Base64 format internally. The Base64 algorithm converts arbitrary data into a readable and printable string representation. As a result of this 3 bytes of arbitrary binary data will occupy 4 bytes of memory.

Reading binary data with this function obviously only makes sense if the property has been assigned the value by a previous call to OBJ_SetBinary(). However using this method any kind of data can be stored by a string property. This can e.g. be interesting when certain data shall be stored in the user accessible part of the devices non-volatile memory.

See also

OBJ_SetBinary(),
OBJ_GetBinaryBufferSize(),
OBJ_GetBinaryBufferMaxSize()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the string property. If this handle does not reference a string property, this function will fail and return an error.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's binary representation of the value.
[in,out]	pBufSize	The size of the user supplied buffer. This value can be larger than the amount of bytes actually needed. To find out how much memory must be allocated to store the binary representation of the string property's data the function OBJ_GetBinaryBufferMaxSize() should be called. When this function returns this parameter will contain the amount of bytes actually filled with data.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetChangedCounter()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetChangedCounter	(	HOBJ	hProp,
		unsigned int *	pChangedCounter )

Returns the current changed counter for this object.

This changed counter is incremented internally each time the object is modified. To find out if this object has been modified since this function has been called keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pChangedCounter	A pointer to a variable that will receive the current changed counter on a successful function call.

OBJ_GetChangedCounterAttr()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetChangedCounterAttr	(	HOBJ	hProp,
		unsigned int *	pChangedCounter )

Returns the current changed counter for this object.

This changed counter is incremented internally each time the objects attributes are modified. To check if this objects attributes have been modified since the last time, this check has been performed, keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date. Attributes are e.g. the flags or a property's translation dictionary, but NOT the property's value.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pChangedCounter	A pointer to a variable that will receive the current changed counter on a successful function call.

OBJ_GetContentDesc()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetContentDesc	(	HOBJ	hList,
		char *	pBuf,
		size_t	bufSize )

Retrieves a string containing information about what's in this list.

This string might not be defined by every list but in any case this function will return a valid string. However this string might be empty.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hList	A handle to the object whose content descriptor shall be returned.
[out]	pBuf	A pointer to a user supplied string buffer receiving the object's content descriptor.
[in]	bufSize	The size of the user supplied string buffer in bytes.

OBJ_GetDictSize()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetDictSize	(	HOBJ	hProp,
		unsigned int *	pDictSize )

Receives the size of the property's translation dictionary.

If the property does define a translation dictionary this function receives the number of elements contained in this dictionary.

The translation dictionary serves two purposes: Once it has been defined this property can only be assigned values ( which can either be passed as a string or as the actual value ) which are contained in the translation table. Thus this makes it very easy to restrict a certain property to a fixed number of values, which can be assigned to it. Properties that have a translation dictionary will typically be defined by declaring a template instance with the type of the enumeration.

The second benefit from a translation dictionary is, that certain values can be assigned a meaningful description via its translation. When a translation table has been defined either the string translation can be used to assign its value or its actual data type. A float property e.g. might define a translation table like this: 'Auto -> 0', 'auto -> 1', 'OnLowLevel -> 2'. Now to set this property to use the 'on low level' trigger mode this can be done by calling one of the following functions

OBJ_SetI( hProp, ctmOnLowLevel, 0 ); // set value via enum type
OBJ_SetS( hProp, "OnLowLevel", 0 ); // set value via the translation string

The string representation can also be extremely useful to populate combo boxes for GUI applications.

EXAMPLE:

//-----------------------------------------------------------------------------
// shows how to read the translation dictionary of a property
TPROPHANDLING_ERROR processDict( HOBJ m_hObj )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR funcResult = PROPHANDLING_NO_ERROR;
  unsigned int size = 0;
  int* pVal = 0;
  char** ppBuf = 0;
  size_t bufSize = 0;
  int i = 0;
  const size_t BUFFER_INCREMENT_FACTOR = 6;
 
  if( ( funcResult = OBJ_GetDictSize( m_hObj, &size ) ) != PROPHANDLING_NO_ERROR )
  {
    return funcResult;
  }
 
  pVal = (int*)calloc( size, sizeof(int) );
  ppBuf = (char**)calloc( size, sizeof(char*) );
  bufSize = DEFAULT_STRING_SIZE_LIMIT, i;
  for( i=0; i<size; i++ )
  {
    ppBuf[i] = (char*)calloc( size, bufSize );
  }
 
  while( ( funcResult = OBJ_GetIDictEntries( m_hObj, ppBuf, bufSize, pVal, size ) ) == PROPHANDLING_INPUT_BUFFER_TOO_SMALL )
  {
    bufSize *= BUFFER_INCREMENT_FACTOR;
    for( i=0; i<size; i++ )
    {
      ppBuf[i] = (char*)realloc( ppBuf[i], bufSize );
    }
  }
 
  if( funcResult == PROPHANDLING_NO_ERROR )
  {
    // now the dictionary has been queried completely -> do something with it
  }
 
  // free memory again
  for( i=0; i<size; i++ )
  {
    free( ppBuf[i] );
  }
  free( ppBuf );
  free( pVal );
  return funcResult;
}

See also

OBJ_GetFDictEntries(),
OBJ_GetIDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property
[out]	pDictSize	A pointer to a variable that will receive the size of the dictionary on a successful function call.

OBJ_GetDisplayName()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetDisplayName	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Retrieves the display name of this object.

This might be an empty string if no display name has been specified.

Since

1.11.20

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object whose display name shall be returned.
[out]	pBuf	A pointer to a user supplied string buffer receiving the object's display name.
[in]	bufSize	The size of the user supplied string buffer in bytes.

OBJ_GetDocString()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetDocString	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Retrieves a string containing general information about the object.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object whose doc string name shall be returned.
[out]	pBuf	A pointer to a user supplied string buffer receiving the object's doc string.
[in]	bufSize	The size of the user supplied string buffer in bytes.

OBJ_GetElementCount()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetElementCount	(	HLIST	hList,
		unsigned int *	pElementCount )

Receives the number of objects stored in a list.

This is a list specific function, which will fail if hList does not reference a an object of type ctList.

The function will receive the number of object entries for the list referenced by hList.

See also

OBJ_GetType(),
OBJ_GetFlags()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hList	A handle to the object list.
[out]	pElementCount	A pointer to a variable that will receive the number of objects referenced by this list on a successful function call.

OBJ_GetF()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetF	(	HOBJ	hProp,
		double *	pVal,
		int	index )

Receives a property's value as a float value.

This is a property related function and it will fail if this object does not reference a property of type ctPropFloat.

To find out if the object referenced by hProp is a float property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetFArray()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFArray	(	HOBJ	hProp,
		double *	pVal,
		unsigned int	valCount,
		int	index )

Receives one or more values from a property as float values.

This is a property related function and it will fail if this object does not reference a property of type ctPropFloat.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

See also

OBJ_GetIArray()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	valCount	The amount of values to store in pVal (the amount of value to read starting at index)
[in]	index	The index of the first value to get(if this property holds more than one value).

OBJ_GetFDictEntries()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFDictEntries	(	HOBJ	hProp,
		char **	pTranslationArray,
		size_t	sizePerTranslationBuf,
		double *	pValArray,
		size_t	arraySizes )

Receives the translation dictionary for a float property.

This function will receive the translation dictionary for a floating point property. On a successful call each element in pTranslationArray will contain the string representation of the same element in pValArray.

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetIDictEntries()

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. In case one or more of the user supplied string buffers are too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased. Please note that all string buffers should have the same size.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationArray	A pointer to an array of user supplied string buffers that will receive the string representation of the property's dictionary. This parameter might be '0' if the value is not required.
[in]	sizePerTranslationBuf	The size of each user supplied string buffer in bytes.
[out]	pValArray	A pointer to a user supplied array of floating point values that will receive the floating point representation of the translation dictionary. This parameter might be '0' if the value is not required.
[in]	arraySizes	The number of elements for both user supplied arrays

OBJ_GetFDictEntry()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFDictEntry	(	HOBJ	hProp,
		char *	pTranslationString,
		size_t	translationStringBufSize,
		double *	pValue,
		int	index )

Receives a single translation dictionary entry for a floating point property.

This function will receive a single translation dictionary entry for a floating point property. On a successful call pTranslationString will contain the string representation of the value in pValue.

Note

A more effective way to query a property's complete translation dictionary is the function OBJ_GetFDictEntries().

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetFDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. If the user supplied string buffer is too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationString	A pointer to a user supplied buffer that receives the string translation of the entry. This parameter might be '0' if the value is not required.
[in]	translationStringBufSize	The size of the user supplied buffer in bytes.
[out]	pValue	A pointer to a variable that will receive integer representation of the entry on a successful function call. This parameter might be '0' if the value is not required.
[in]	index	The index starting from 0 of the translation entry to return.

OBJ_GetFirstChild()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFirstChild	(	HOBJ	hObj,
		HOBJ *	phFirstChild )

Moves to the first child of this object(moves down one level).

Please see the code samples provided in the description of function OBJ_GetFirstSibling() to find out how to work with this function.

See also

OBJ_GetNextSibling(),
OBJ_GetFirstSibling(),
OBJ_GetParent()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to the object whose first child is needed.
[out]	phFirstChild	A pointer to the variable which receives the new handle on a successful function call.

OBJ_GetFirstSibling()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFirstSibling	(	HOBJ	hObj,
		HOBJ *	phFirstSibling )

Moves to the first sibling of this object.

This function together with the function from the 'See also' section can be used to navigate within an object hierarchy.

Consider the following structure:

LA
|-LB
|-LC
|  |-PE
|  |-PF
|  |-PG
|-PD

Where the prefix 'L' means, that this is an object list, 'P' that this is a property.

Example 1:

HOBJ hObj;
// some function that retrieves the handle to list 'C'
getHToLC(&hObj);
OBJ_GetFirstChild( hObj, &hObj );   // now we are referencing 'PE'
OBJ_GetLastSibling( hObj, &hObj );  // moves to 'PG'
OBJ_GetFirstChild( hObj, &hObj );   // moves back to 'PE'
OBJ_GetNextSibling( hObj, &hObj );  // moves to 'PF'
OBJ_GetFirstSibling( hObj, &hObj ); // moves back to PE'
OBJ_GetParent( hObj, &hObj );       // we are referencing 'LC' again

Example 2:

Iterate over a complete list including sub lists:

//------------------------------------------------------------------------------
void ParseList( HOBJ hObj )
//------------------------------------------------------------------------------
{
  TComponentType type;
  while( OBJ_CheckHandle( hObj, hcmFull ) == PROPHANDLING_NO_ERROR )
  {
    OBJ_GetType( hObj, &type );
    if( type == ctList )
    {
      // do some list specific stuff
      OBJ_GetFirstChild( hObj, &hObj );
      ParseList( hObj );
    }
    else if( type & ctProp )
    {
      // do property specific stuff e.g. read the value
      char buf[DEFAULT_STRING_SIZE_LIMIT];
      if( OBJ_GetSFormatted( hObj, &buf, DEFAULT_STRING_SIZE_LIMIT, 0, 0 ) == PROPHANDLING_NO_ERROR )
      {
        printf( "Val: %s\n", buf );
      }
      else
      {
        printf( "Error, can't read property value\n" );
      }
    }
    OBJ_GetNextSibling( hObj, &hObj );
  }
}
 
//-----------------------------------------------------------------------------
int main(int argc, char* argv[])
//-----------------------------------------------------------------------------
{
  HLIST hSetting;
  // ....
  if( DMR_FindList( hDrv, "Base", dmltSetting, 0, &hSetting ) == DMR_NO_ERROR )
  {
    ParseList(hSetting);
  }
  // ....
  return 0;
}

See also

OBJ_GetNextSibling(),
OBJ_GetFirstChild(),
OBJ_GetLastSibling(),
OBJ_GetParent()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to the object whose first sibling is needed.
[out]	phFirstSibling	A pointer to the variable which receives the new handle on a successful function call.

OBJ_GetFlags()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFlags	(	HOBJ	hObj,
		TComponentFlag *	pFlags )

Receives the flags associated with this object.

See also

OBJ_GetFlagsS()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pFlags	A pointer to a variable that will receive the objects flags on a successful function call.

OBJ_GetFlagsS()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFlagsS	(	HOBJ	hObj,
		const char *	pSeparator,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of the flags associated with this object.

See also

OBJ_GetFlags()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[in]	pSeparator	A const C-string defining a string used to separate the individual flags of the object
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects flags as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_GetFormatString()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetFormatString	(	HOBJ	hProp,
		char *	pBuf,
		size_t	bufSize )

Retrieves the internal format string this property uses to convert data to strings.

This format string is used internally whenever the user reads a property's value as a string without specifying a custom format string and the property is not a string type property.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the object whose format string shall be returned.
[out]	pBuf	A pointer to a user supplied string buffer receiving the object's format string.
[in]	bufSize	The size of the user supplied string buffer in bytes.

OBJ_GetHandle()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetHandle	(	HLIST	hList,
		const char *	pPathAndPropName,
		HOBJ *	phObj )

Retrieves an objects handle(deprecated).

Deprecated

This function has been declared deprecated. Use OBJ_GetHandleEx() instead.

This function tries to retrieve an objects handle. This handle is needed for almost every other object related function.

The functions always needs an object list from where to start the search for the object specified by pPathAndPropName. The handle to that list e.g. can be obtained by calling the function DMR_FindList() or any other function that returns a HLIST type.

EXAMPLE:

//-----------------------------------------------------------------------------
HOBJ getExposeProp( HDRV hDrv )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR objResult;
  TDMR_ERROR dmrResult;
  HOBJ hProp_expose_us;
  HLIST hList;
 
  // First locate the setting list named 'Base', which is always present
  if( ( dmrResult = DMR_FindList( hDrv, "Base", dmltSetting, 0, &hList ) ) == DMR_NO_ERROR )
  {
    // Now try to locate the property named 'Expose_us' to control the exposure time
    if( ( objResult = OBJ_GetHandle( baseList, "Expose_us", &hProp_expose_us ) ) != PROPHANDLING_NO_ERROR )
    {
      printf( "OBJ_GetHandle failed: %d Handle: %d\n", objResult, hProp_expose_us );
    }
  }
  else
  {
    printf( "DMR_FindList failed: %d\n", dmrResult );
  }
  return hProp_expose_us;
}

The function will first try to locate the specified object inside the current list and if an object with the specified name can not be located the full tree of sub lists inside the current list will be scanned for an object with a matching name as well. The handle to the first object detected during that search will be returned.

There might be situations where several objects with the same name reside in sub lists of the list currently referenced. E.g. a list of lists containing features describing digital inputs where each sub list has a property State.

DigitalInputs
|-DigIn0
|  |-State
|-DigIn1
|  |-State
|-DigIn2
|  |-State
|-DigIn3
|  |-State

In that case the path to the property must be passed as well. Assuming that the property State in the sub list DigIn2 shall be located the call to OBJ_GetHandle() must be modified like this:

// Now try to locate the property named 'State' in the sub list 'DigIn2'.
if( ( objResult = OBJ_GetHandle( hDigitalInputs, "DigIn2/State", &hProp_state ) ) != PROPHANDLING_NO_ERROR )
{
  printf( "OBJ_GetHandle failed: %d Handle: %d\n", objResult, hProp_state );
}

To find out where to search for a certain property some research work is required, which is done best using the tool ImpactControlCenter as it lists all properties the user might need to access in a hierarchical manner. Also the structure of the driver interface might be much easier to understand when looking a this tree structure.

See also

DMR_FindList(),
OBJ_GetHandleEx()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hList	The list in which to search for the object.
[in]	pPathAndPropName	The path and/or name of the object to be located.
[out]	phObj	A pointer to the variable that will receive the objects handle on a successful call to this function. If a component could not be located because it is not implemented or pObjName specifies a non-existing component the variable pointed to by phObj might contain INVALID_ID after calling this function.

OBJ_GetHandleEx()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetHandleEx	(	HLIST	hList,
		const char *	pObjName,
		HOBJ *	phObj,
		unsigned int	searchMode,
		int	maxSearchDepth )

Retrieves an objects handle.

This function tries to retrieve an objects handle. This handle is needed for almost every other object related function.

In general this function behaves exactly like the function OBJ_GetHandle() except that it allows the user to control the way how to search for objects in a more sophisticated way.

See also

DMR_FindList(),
OBJ_GetHandle()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hList	The list in which to search for the object.
[in]	pObjName	The path and/or name of the object to be located.
[out]	phObj	A pointer to the variable that will receive the objects handle on a successful call to this function. If a component could not be located because it is not implemented or pObjName specifies a non-existing component the variable pointed to by phObj might contain INVALID_ID after calling this function.
[in]	searchMode	Specifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: smIgnoreLists smIgnoreMethods smIgnoreProperties
[in]	maxSearchDepth	The maximum depth (in lists) where to search for the component. By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

OBJ_GetI()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetI	(	HOBJ	hProp,
		int *	pVal,
		int	index )

Receives a property's value as an integer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt or ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetI64()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetI64	(	HOBJ	hProp,
		int64_type *	pVal,
		int	index )

Receives a property's value as an integer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt64.

To find out if the object referenced by hProp is a 64 bit integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetI64Array()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetI64Array	(	HOBJ	hProp,
		int64_type *	pVal,
		unsigned int	valCount,
		int	index )

Receives one or more values from a property as 64 bit integer values.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

See also

OBJ_GetIArray()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	valCount	The amount of values to store in pVal (the amount of value to read starting at index)
[in]	index	The index of the first value to get(if this property holds more than one value).

OBJ_GetI64DictEntries()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetI64DictEntries	(	HOBJ	hProp,
		char **	pTranslationArray,
		size_t	sizePerTranslationBuf,
		int64_type *	pValArray,
		size_t	arraySizes )

Receives the translation dictionary for an integer property.

This function will receive the translation dictionary for an integer property. On a successful call each element in pTranslationArray will contain the string representation of the same element in pValArray.

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetFDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. In case one or more of the user supplied string buffers are too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased. Please note that all string buffers should have the same size.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationArray	A pointer to an array of user supplied string buffers that will receive the string representation of the property's dictionary. This parameter might be '0' if the value is not required.
[in]	sizePerTranslationBuf	The size of each user supplied string buffer in bytes.
[out]	pValArray	A pointer to a user supplied array of 64 bit integer values that will receive the 64 bit integer representation of the translation dictionary. This parameter might be '0' if the value is not required.
[in]	arraySizes	The number of elements for both user supplied arrays

OBJ_GetI64DictEntry()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetI64DictEntry	(	HOBJ	hProp,
		char *	pTranslationString,
		size_t	translationStringBufSize,
		int64_type *	pValue,
		int	index )

Receives a single translation dictionary entry for a 64 bit integer property.

This function will receive a single translation dictionary entry for a 64 bit integer property. On a successful call pTranslationString will contain the string representation of the value in pValue.

Note

A more effective way to query a property's complete translation dictionary is the function OBJ_GetIDictEntries().

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetIDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. If the user supplied string buffer is too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationString	A pointer to a user supplied buffer that receives the string translation of the entry. This parameter might be '0' if the value is not required.
[in]	translationStringBufSize	The size of the user supplied buffer in bytes.
[out]	pValue	A pointer to a variable that will receive the 64 bit integer representation of the entry on a successful function call. This parameter might be '0' if the value is not required.
[in]	index	The index starting from 0 of the translation entry to return.

OBJ_GetIArray()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetIArray	(	HOBJ	hProp,
		int *	pVal,
		unsigned int	valCount,
		int	index )

Receives one or more values from a property as integer values.

Integer properties can store more than a single value. For example a property LUTValues8Bit could store 256 integer values defining the LUT(Look Up Table). To query the last 56 values, call OBJ_GetIArray( hProp, &values, 56, 200 ).

This is a property related function and it will fail if this object does not reference a property of type ctPropInt or ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	valCount	The amount of values to store in pVal (the amount of value to read starting at index)
[in]	index	The index of the first value to get(if this property holds more than one value).

OBJ_GetIDictEntries()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetIDictEntries	(	HOBJ	hProp,
		char **	pTranslationArray,
		size_t	sizePerTranslationBuf,
		int *	pValArray,
		size_t	arraySizes )

Receives the translation dictionary for an integer property.

This function will receive the translation dictionary for an integer property. On a successful call each element in pTranslationArray will contain the string representation of the same element in pValArray.

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetFDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. In case one or more of the user supplied string buffers are too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased. Please note that all string buffers should have the same size.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationArray	A pointer to an array of user supplied string buffers that will receive the string representation of the property's dictionary. This parameter might be '0' if the value is not required.
[in]	sizePerTranslationBuf	The size of each user supplied string buffer in bytes.
[out]	pValArray	A pointer to a user supplied array of integer values that will receive the integer representation of the translation dictionary. This parameter might be '0' if the value is not required.
[in]	arraySizes	The number of elements for both user supplied arrays

OBJ_GetIDictEntry()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetIDictEntry	(	HOBJ	hProp,
		char *	pTranslationString,
		size_t	translationStringBufSize,
		int *	pValue,
		int	index )

Receives a single translation dictionary entry for an integer property.

This function will receive a single translation dictionary entry for an integer property. On a successful call pTranslationString will contain the string representation of the value in pValue.

Note

A more effective way to query a property's complete translation dictionary is the function OBJ_GetIDictEntries().

See also

OBJ_GetDictSize() (also for information about translation dictionaries),
OBJ_GetIDictEntries()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise. If the user supplied string buffer is too small to store the translation string in it a PROPHANDLING_INPUT_BUFFER_TOO_SMALL error will returned. In that case the user supplied string buffers size should be increased.

Parameters

[in]	hProp	A handle to the property.
[out]	pTranslationString	A pointer to a user supplied buffer that receives the string translation of the entry. This parameter might be '0' if the value is not required.
[in]	translationStringBufSize	The size of the user supplied buffer in bytes.
[out]	pValue	A pointer to a variable that will receive the integer representation of the entry on a successful function call. This parameter might be '0' if the value is not required.
[in]	index	The index starting from 0 of the translation entry to return.

OBJ_GetLastSibling()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetLastSibling	(	HOBJ	hObj,
		HOBJ *	phLastSibling )

Moves to the last sibling in the current list.

Please see the code samples provided in the description of function OBJ_GetFirstSibling() to find out how to work with this function.

See also

OBJ_GetFirstSibling(),
OBJ_GetFirstChild(),
OBJ_GetNextSibling(),
OBJ_GetParent()

Since

1.10.64

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to the object whose last sibling is needed.
[out]	phLastSibling	A pointer to the variable which receives the new handle on a successful function call.

OBJ_GetMaxValCount()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetMaxValCount	(	HOBJ	hProp,
		unsigned int *	pValCount )

Receives the maximum number of values this property can store.

See also

OBJ_SetValCount(), OBJ_GetValCount()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pValCount	A pointer to a variable that will receive the maximum value count for this property on a successful function call.

OBJ_GetName()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetName	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Retrieves the name of this object.

This group contains functions for accessing properties, methods and lists.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object whose name shall be returned.
[out]	pBuf	A pointer to a user supplied string buffer receiving the object's name.
[in]	bufSize	The size of the user supplied string buffer in bytes.

OBJ_GetNextSibling()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetNextSibling	(	HOBJ	hObj,
		HOBJ *	phNextSibling )

Moves to the next sibling of this object.

Please see the code samples provided in the description of function OBJ_GetFirstSibling() to find out how to work with this function.

See also

OBJ_GetFirstSibling(),
OBJ_GetFirstChild(),
OBJ_GetLastSibling(),
OBJ_GetParent()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to the object whose next sibling is needed.
[out]	phNextSibling	A pointer to the variable which receives the new handle on a successful function call.

OBJ_GetP()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetP	(	HOBJ	hProp,
		void **	pVal,
		int	index )

Receives a property's value as a pointer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropPtr.

To find out if the object referenced by hProp is a pointer property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a variable that will receive the value on a successful function call.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetParent()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetParent	(	HOBJ	hObj,
		HOBJ *	phParent )

Moves to the parent object(moves up one level).

Please see the code samples provided in the description of function OBJ_GetFirstSibling() to find out how to work with this function.

See also

OBJ_GetNextSibling(),
OBJ_GetFirstChild(),
OBJ_GetFirstSibling()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	The handle to the object whose parent object is needed.
[out]	phParent	A pointer to the variable which receives the new handle on a successful function call.

OBJ_GetRepresentation()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetRepresentation	(	HOBJ	hObj,
		TComponentRepresentation *	pRepresentation )

Receives the recommended representation associated with this object.

The representation can be used e.g. to develop a GUI that creates convenient controls for certain features.

See also

OBJ_GetFlags()

Since

2.14.0

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pRepresentation	A pointer to a variable which will receive the objects recommended representation.

OBJ_GetRepresentationS()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetRepresentationS	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of the recommended representation of the referenced object.

This function queries a string representation of the recommended representation of the object currently referenced by hObj.

See also

OBJ_GetRepresentation()

Since

2.14.0

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects recommended representation as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_GetS()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetS	(	HOBJ	hProp,
		char *	pVal,
		size_t	bufSize,
		int	index )

Receives a property's value as a string.

This is a property related function and it will fail if this object does not reference a property of type ctPropString.

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

To read a property of a different type as a string call the function OBJ_GetSFormatted().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to a user supplied buffer that receives the property's value.
[in]	bufSize	The size of the user supplied buffer in bytes.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_GetSArrayFormatted()

MVDMR_API TPROPHANDLING_ERROR DMR_CALL OBJ_GetSArrayFormatted	(	HOBJ	hProp,
		char *	pBuf,
		size_t	bufSize,
		const char *	pFormat,
		const char *	pDelimiters,
		int	startIndex,
		int	endIndex,
		int	mode )

Receives a set of values stored by the property(deprecated).

Deprecated

This function has been declared deprecated. Use OBJ_GetSArrayFormattedEx() instead.

This is a property related function and it will fail if this object does not specify the ctProp flag.

Every property can be read this way. If the user doesn't provide a custom format string an internal default format will be used to convert the value into a string.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's value.
[in]	bufSize	The size of the user supplied buffer in bytes.
[in]	pFormat	A pointer to a user supplied format string or NULL or an empty string if the internal default shall be used.
[in]	pDelimiters	A pointer to a user supplied delimiter string which will be used to separate the individual values.
[in]	startIndex	The index of the first value to read.
[in]	endIndex	The index of the last of the desired values. If INT_MAX is passed, every from startIndex to the last value stored by the property will be returned.
[in]	mode	Specifies the mode this function operates in. Currently only the LSB affects the behaviour of this function. When the LSB is set, the translation dictionary (if defined) will be ignored for this call.

OBJ_GetSArrayFormattedEx()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSArrayFormattedEx	(	HOBJ	hProp,
		char *	pBuf,
		size_t *	pBufSize,
		const char *	pFormat,
		const char *	pDelimiters,
		int	startIndex,
		int	endIndex,
		int	mode )

Receives a set of values stored by the property.

This is a property related function and it will fail if this object does not specify the ctProp flag.

Every property can be read this way. If the user doesn't provide a custom format string an internal default format will be used to convert the value into a string.

EXAMPLE:

Assuming that 'hProp' references a property, that stores three values '1', '2' and '666'

TPROPHANDLING_ERROR errorCode;
HOBJ hProp;
char* pBuf = 0;
size_t bufSize = 0;
hProp = getHandleFromSomewhere();
OBJ_SetI( hProp, 1, 0 );
OBJ_SetI( hProp, 2, 1 );
OBJ_SetI( hProp, 666, 2 );
errorCode = OBJ_GetSArrayFormattedEx( hProp, 0, &bufSize, 0, "&&:&&", 0, INT_MAX, 1 );
pBuf = (char*)calloc(bufSize, sizeof(char));
errorCode = OBJ_GetSArrayFormattedEx( hProp, pBuf, &bufSize, 0, "&&:&&", 0, INT_MAX, 1 );
// this should result in 'buf' containing "1&&:&&2&&:&&666" now
free(pBuf);

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's value. This can be 0 when pBufSize points to a valid location. Then pBufSize will contain the size in bytes needed for pBuf after the call to this function.
[in]	pBufSize	The size of the user supplied buffer in bytes.
[in]	pFormat	A pointer to a user supplied format string or NULL or an empty string if the internal default shall be used.
[in]	pDelimiters	A pointer to a user supplied delimiter string which will be used to separate the individual values.
[in]	startIndex	The index of the first value to read.
[in]	endIndex	The index of the last of the desired values. If INT_MAX is passed, every from startIndex to the last value stored by the property will be returned.
[in]	mode	Specifies the mode this function operates in. Currently only the LSB affects the behaviour of this function. When the LSB is set, the translation dictionary (if defined) will be ignored for this call.

OBJ_GetSelectedFeatures()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSelectedFeatures	(	HOBJ	hObj,
		int	index,
		HOBJ *	phFeatures,
		size_t *	pFeatureCount )

Retrieves the list of object handles of objects that are selected by this object.

This function retrieves the list of object handles of objects, that are selected by the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When an object 'selects' other objects, this indicates, that selected objects may change whenever the selecting object changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

See also

OBJ_GetHandle(),
OBJ_GetSelectingFeatures()

Since

1.11.20

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object whose display table of selected objects shall be returned.
[in]	index	The index of the first feature to query. This should be 0 if all features shall be queried.
[out]	phFeatures	A pointer to an array of object handles allocated by the user that shall retrieve the handles to the selected objects. This can be 0 if only the amount of selected features shall be queried.
[in,out]	pFeatureCount	A pointer to the variable containing the size of the array pointed to by phFeatures and retrieving the number of features selected by this object if phFeatures is 0.

OBJ_GetSelectingFeatures()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSelectingFeatures	(	HOBJ	hObj,
		int	index,
		HOBJ *	phFeatures,
		size_t *	pFeatureCount )

Retrieves the list of object handles of objects that are selecting this object.

This function retrieves the list of object handles of objects, that are selecting the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When an object 'selects' other objects, this indicates, that selected objects may change whenever the selecting object changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

See also

OBJ_GetHandle(),
OBJ_GetSelectedFeatures()

Since

1.11.20

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object whose display table of selected objects shall be returned.
[in]	index	The index of the first feature to query. This should be 0 if all features shall be queried.
[in]	phFeatures	A pointer to an array of object handles allocated by the user that shall retrieve the handles to the selected objects. This can be 0 if only the amount of selected features shall be queried.
[in,out]	pFeatureCount	A pointer to the variable containing the size of the array pointed to by phFeatures and retrieving the number of features selecting this object if phFeatures is 0.

OBJ_GetSFormatted()

MVDMR_API TPROPHANDLING_ERROR DMR_CALL OBJ_GetSFormatted	(	HOBJ	hProp,
		char *	pBuf,
		size_t	bufSize,
		const char *	pFormat,
		int	index )

Receives a property's value as a formatted string(deprecated).

Deprecated

This function has been declared deprecated. Use OBJ_GetSFormattedEx() instead.

This is a property related function and it will fail if this object does not specify the ctProp flag.

Every property can be read this way. If the user doesn't provide a custom format string an internal default format will be used to convert the value into a string.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's value.
[in]	bufSize	The size of the user supplied buffer in bytes.
[in]	pFormat	A pointer to a user supplied format string or NULL or an empty string if the internal default shall be used.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_GetSFormattedEx()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSFormattedEx	(	HOBJ	hProp,
		char *	pBuf,
		size_t *	pBufSize,
		const char *	pFormat,
		int	index )

Receives a property's value as a formatted string.

This is a property related function and it will fail if this object does not specify the ctProp flag.

Every property can be read this way. If the user doesn't provide a custom format string an internal default format will be used to convert the value into a string.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pBuf	A pointer to a user supplied buffer that receives the property's value. This can be 0 when pBufSize points to a valid location. Then pBufSize will contain the size in bytes needed for pBuf after the call to this function.
[in,out]	pBufSize	A pointer to a variable that contains the size of the buffer pointed to by pBuf. This variable will receive the size needed for pBuf in bytes if pBuf is 0.
[in]	pFormat	A pointer to a user supplied format string or NULL or an empty string if the internal default shall be used.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_GetSParamList()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSParamList	(	HOBJ	hMeth,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of a methods parameter list.

This is a method specific function, which will fail if hMeth does not reference a an object of type ctMeth.

This function returns a string containing one character for each parameter this method object expects and one for the return type of the function call.

The first character is the return type of the function all others are parameters. void functions don't specify parameters.

The characters have the following meaning:

• i specifies a 32-bit integer value
• I specifies a 64-bit integer value
• s specifies a pointer to a C-string
• f specifies a double precision float value
• p specifies a pointer value
• v specifies a void return value

Examples:

• 'v': This is a function returning nothing (void). It expects no parameters.
• 'viis': This is a function returning nothing (void). It expects 2 integer values and one pointer to a C-string.
• 'if': This function returns an integer value and expects a float value.

See also

OBJ_Execute(),
OBJ_GetType(),
or use OBJ_GetSWithInplaceConstruction() with sqMethParamString for a more efficient version of this function

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hMeth	A handle to the method object
[out]	pBuf	A pointer to a user supplied buffer which will receive the methods parameter list as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_GetSWithInplaceConstruction()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetSWithInplaceConstruction	(	HOBJ	hObj,
		TOBJ_StringQuery	sq,
		char **	pResult,
		SCF	pConstructionFunc,
		int	mode,
		int	reserved )

A more sophisticated and efficient way to read string values from this module.

This methods provides an efficient way to query string values without the risk of allocating a too small buffer.

By passing a pointer to an allocator function the user can control the way the string is constructed directly. A pointer to the string is returned to the user on a successful call, which must be used to de-allocate the string if it's no longer needed.

EXAMPLE:

//-----------------------------------------------------------------------------
char* stringAllocator( const char* pBuf, size_t reqBufSize )
//-----------------------------------------------------------------------------
{
  char* pStr = new char[reqBufSize];
  return strcpy( pStr, pBuf );
}
 
//-----------------------------------------------------------------------------
void fn( HOBJ hObj )
//-----------------------------------------------------------------------------
{
  char* pStr = 0;
  if( OBJ_GetSWithInplaceConstruction( m_hObj, sqObjName, &pStr, stringAllocator, 0, 0 ) == PROPHANDLING_NO_ERROR )
  {
    printf( "the name: %s\n", pStr );
  }
  delete [] pStr;
}

EXAMPLE:

//-----------------------------------------------------------------------------
void fn( HOBJ hObj )
//-----------------------------------------------------------------------------
{
  char* pStr = 0;
  if( OBJ_GetSWithInplaceConstruction( m_hObj, sqObjName, &pStr, 0, 0, 0 ) == PROPHANDLING_NO_ERROR )
  {
    printf( "the name: %s\n", pStr );
  }
  OBJ_FreeSMemory( pStr );
}

The function can also be used without passing an allocator function, but the user can't control the way the string is build, and must call a special cleanup function in order to avoid memory leaks.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the property.
[in]	sq	The parameter to receive as a string.
[out]	pResult	A pointer to a pointer that will receive the result on a successful function call.
[in]	pConstructionFunc	A pointer to the user supplied allocator function. This parameter can be 0, but then the memory must be freed using the function OBJ_FreeSMemory().
[in]	mode	Currently not supported. Must be 0.
[in]	reserved	If sq equals sqPropVal this parameter can be used as the value index (see OBJ_GetSFormatted())

OBJ_GetType()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetType	(	HOBJ	hObj,
		TComponentType *	pType )

Receives the type of the referenced object.

This function queries the type of the object currently referenced by hObj.

EXAMPLE:

//-----------------------------------------------------------------------------
// This function checks whether the object referenced by \a hObj is a property or not.
int isProperty( HOBJ hObj )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR errorCode;
  TComponentType type;
  int result = -1;
 
  if( ( errorCode = OBJ_GetType( hObj, &type ) ) == PROPHANDLING_NO_ERROR )
  {
    // Now try to locate the property named 'Expose_us' to control the exposure time
    if( type & ctProp )
    {
      // this is a property
      result = 1;
    }
    else
    {
      // this is NOT a property
      result = 0;
    }
  }
  else
  {
    // handle valid?
    printf( "OBJ_GetType failed: %d\n", dmrResult );
  }
  return result;
}

See also

OBJ_GetTypeS()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pType	A pointer to a variable which will receive the objects type.

OBJ_GetTypeS()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetTypeS	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of the type of the referenced object.

This function queries a string representation of the type of the object currently referenced by hObj.

See also

OBJ_GetType()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects type as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_GetValCount()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetValCount	(	HOBJ	hProp,
		unsigned int *	pValCount )

Receives the current number of values stored by the property.

See also

OBJ_SetValCount(), OBJ_GetMaxValCount()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pValCount	A pointer to a variable that will receive the value count for this property on a successful function call.

OBJ_GetVisibility()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetVisibility	(	HOBJ	hObj,
		TComponentVisibility *	pVisibility )

Receives the recommended visibility associated with this object.

The visibility can be used e.g. to develop a GUI that displays a crucial subset of features only.

See also

OBJ_GetFlags()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pVisibility	A pointer to a variable which will receive the objects recommended visibility.

OBJ_GetVisibilityS()

TPROPHANDLING_ERROR DMR_CALL OBJ_GetVisibilityS	(	HOBJ	hObj,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of the recommended visibility of the referenced object.

This function queries a string representation of the recommended visibility of the object currently referenced by hObj.

See also

OBJ_GetVisibility()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects recommended visibility as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_IsConstantDefined()

TPROPHANDLING_ERROR DMR_CALL OBJ_IsConstantDefined	(	HOBJ	hProp,
		int	constant,
		unsigned int *	pResult )

Checks if a certain constant for this property is defined.

This is a property related function and it will fail if this object does not specify the ctProp flag.

To find out if the object referenced by hProp is a property call the function OBJ_GetType().

Valid constants to query are:

• PROP_MAX_VAL
• PROP_MIN_VAL
• PROP_STEP_WIDTH

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the object.
[in]	constant	The constant to check for
[out]	pResult	A pointer to the variable that receives the result on a successful call to the function. A return value different from '0' indicates, that this property defines the constant in question.

OBJ_IsDefault()

TPROPHANDLING_ERROR DMR_CALL OBJ_IsDefault	(	HOBJ	hObj,
		unsigned int *	pResult )

Checks if the object is set to its default value.

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hObj	A handle to the object.
[out]	pResult	A pointer to the variable that receives the result on a successful call to the function. A return value different from '0' indicates, that this object is currently set to the default value.

OBJ_IsSettingAvailable()

TPROPHANDLING_ERROR DMR_CALL OBJ_IsSettingAvailable	(	const char *	pName,
		TStorageFlag	storageFlags,
		TScope	scope )

Checks if a certain setting is available.(deprecated)

Deprecated

This function has been declared deprecated and might be removed in future versions of this interface. Use DMR_IsSettingAvailable() instead.

Returns

• PROPHANDLING_NO_ERROR if the setting is available.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	pName	The name of the setting to look for.
[in]	storageFlags	The flags defining which information shall be read from the location and how this information shall be interpreted. This parameter MUST be set to one of the following values: sfNative sfFile sfRAM
[in]	scope	Specifies where to look for the setting.

OBJ_RemoveVal()

TPROPHANDLING_ERROR DMR_CALL OBJ_RemoveVal	(	HOBJ	hProp,
		int	index )

Removes a certain value from a property.

This is a property related function and it will fail if this object does not specify the ctProp flag.

To find out if the object referenced by hProp is a property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_RepresentationToString()

TPROPHANDLING_ERROR DMR_CALL OBJ_RepresentationToString	(	TComponentRepresentation	representation,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of a component representation passed to the function.

This function queries a string representation of a component representation passed to the function.

See also

OBJ_GetRepresentation()

Since

2.14.0

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	representation	The recommended representation to retrieve the string representation for.
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects recommended representation as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

OBJ_RestoreDefault()

TPROPHANDLING_ERROR DMR_CALL OBJ_RestoreDefault

(

HOBJ

hObj

)

Restores the default for the referenced object.

Calling this function will restore the default value for this object.

If this function is called for an object of type ctList every object in that list is restored to the default value.

Note

The caller must have the right to modify the object. Otherwise this call will fail.

See also

OBJ_IsDefault(),
OBJ_GetType(),
OBJ_GetFlags()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]

hObj

A handle to the object.

OBJ_SetBinary()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetBinary	(	HOBJ	hProp,
		const char *	pBuf,
		unsigned int	bufSize,
		int	index )

Writes binary data to a string property.

This is a string property related function and it will fail if this object does not specify the ctPropString flag(s).

To find out if the object referenced by hProp is a string property call the function OBJ_GetType().

Binary data can only be stored in string properties. When writing binary data to a string property it's stored in Base64 format internally. The Base64 algorithm converts arbitrary data into a read and printable string representation. As a result of this 3 bytes of arbitrary binary data will occupy 4 bytes of memory.

By writing binary data with this function arbitrary data can be stored by a string property. This can e.g. be interesting when certain data shall be stored in the user accessible part of the devices non-volatile memory.

To find out if a property contains binary data check if cfContainsBinaryData is set e.g. by calling

TComponentFlag flags = cfUndefined;
HOBJ hObj = getHandleFromSomewhere();
if( OBJ_GetFlags( hObj, &flags ) == PROPHANDLING_NO_ERROR )
{
  if( flags & cfContainsBinaryData )
  {
    // Yes!! Binary data
  }
}

Performance considerations:

Impact Acquire 2.15.0 and newer:

• Base64 encoding/decoding only is performed when read string data previously written as binary data and vice versa.
• encoding/decoding only is performed if the 2 internal caches are out of sync. so only on the first read access using the other format.
• this version is more efficient compared to previous implementations.

Impact Acquire versions smaller than 2.15.0

• Base64 encoding/decoding always is performed when reading/writing data in binary format.

Note

When a property stores binary data that came from a GenICam chunk buffer additional copy operations from the GenApi runtime will take place. This can be considered as an additional copy operation into the application binary buffer. So binary chunk data should be avoided if possible!

See also

OBJ_GetBinaryEx(),
OBJ_GetBinaryBufferSize(),
OBJ_GetBinaryBufferMaxSize()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the string property. If this handle does not reference a string property, this function will fail and return an error.
[in]	pBuf	A pointer to a user supplied buffer that contains the binary block of data.
[in]	bufSize	The size of the user supplied buffer.
[in]	index	The index of the value to get(if this property holds more than one value).

OBJ_SetF()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetF	(	HOBJ	hProp,
		double	val,
		int	index )

Sets a property's value as a float value.

This is a property related function and it will fail if this object does not reference a property of type ctPropFloat.

To find out if the object referenced by hProp is a float property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	val	The new value for the property.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_SetFArray()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetFArray	(	HOBJ	hProp,
		const double *	pVal,
		unsigned int	valCount,
		int	index )

Sets one or more values from a property as float values.

This is a property related function and it will fail if this object does not reference a property of type ctPropFloat.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

See also

OBJ_GetIArray()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to an array of new values for the property.
[in]	valCount	The amount of values stored in pVal (the amount of value to write starting at index).
[in]	index	The index of the first value to set(if this property holds more than one value).

OBJ_SetI()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetI	(	HOBJ	hProp,
		int	val,
		int	index )

Sets a property's value as an integer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt or ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	val	The new value for the property.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_SetI64()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetI64	(	HOBJ	hProp,
		int64_type	val,
		int	index )

Sets a property's value as a 64 bit integer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt64.

To find out if the object referenced by hProp is a 64 bit integer property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	val	The new value for the property.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_SetI64Array()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetI64Array	(	HOBJ	hProp,
		const int64_type *	pVal,
		unsigned int	valCount,
		int	index )

Sets one or more values from a property as 64 bit integer values.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt or ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

See also

OBJ_GetIArray()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to an array of new values for the property.
[in]	valCount	The amount of values stored in pVal (the amount of value to write starting at index).
[in]	index	The index of the first value to set(if this property holds more than one value).

OBJ_SetIArray()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetIArray	(	HOBJ	hProp,
		const int *	pVal,
		unsigned int	valCount,
		int	index )

Sets one or more values from a property as integer values.

This is a property related function and it will fail if this object does not reference a property of type ctPropInt or ctPropInt64.

To find out if the object referenced by hProp is an integer property call the function OBJ_GetType().

This function can also be used to query certain constants, that may be defined for this property. These constants can include e.g. an upper and a lower limit. To check if a certain constant is defined for this property call the function OBJ_IsConstantDefined(). To query a constant pass the 'PROP_xxxx' values described under OBJ_IsConstantDefined() as index.

See also

OBJ_GetIArray()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[out]	pVal	A pointer to an array of new values for the property.
[in]	valCount	The amount of values stored in pVal (the amount of value to write starting at index).
[in]	index	The index of the first value to set(if this property holds more than one value).

OBJ_SetP()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetP	(	HOBJ	hProp,
		void *	val,
		int	index )

Sets a property's value as a pointer value.

This is a property related function and it will fail if this object does not reference a property of type ctPropPtr.

To find out if the object referenced by hProp is a pointer property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	val	The new value for the property.
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_SetS()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetS	(	HOBJ	hProp,
		const char *	pVal,
		int	index )

Sets a property by string.

This is a property related function and it will fail if this object does not specify the ctProp flag.

To find out if the object referenced by hProp is a property call the function OBJ_GetType().

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	pVal	A pointer to the string containing the new value for this property
[in]	index	The index of the value to set(if this property holds more than one value).

OBJ_SetValCount()

TPROPHANDLING_ERROR DMR_CALL OBJ_SetValCount	(	HOBJ	hProp,
		unsigned int	valCount )

Resizes the property's data array.

This function resizes the internal data array of this property. The size of this array represents the number of values, which can be stored within the property. This function will only succeed, if the cfFixedSize is NOT set for this property and the user has write rights(cfWriteAccess) for this property. Otherwise the function will fail. Whenever the user successfully writes an array of values to a property and this array contains more elements then the current internal data array can accommodate at the desired offset the internal data array will be increased automatically.

Note

If the caller does not have the needed rights this function will fails. To execute This function the cfWriteAccess must be set.

See also

OBJ_GetFlags(),
OBJ_GetValCount(), OBJ_GetMaxValCount()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hProp	A handle to the property.
[in]	valCount	The new val count for the property.

OBJ_VisibilityToString()

TPROPHANDLING_ERROR DMR_CALL OBJ_VisibilityToString	(	TComponentVisibility	visibility,
		char *	pBuf,
		size_t	bufSize )

Receives a string representation of a component visibility passed to the function.

This function queries a string representation of a component visibility passed to the function.

See also

OBJ_GetVisibility()

Returns

• PROPHANDLING_NO_ERROR if successful.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	visibility	The recommended visibility to retrieve the string representation for.
[out]	pBuf	A pointer to a user supplied buffer which will receive the objects recommended visibility as a string on a successful function call.
[in]	bufSize	The size of the user supplied buffer in bytes.

Variable Documentation

DEFAULT_STRING_SIZE_LIMIT

const unsigned int DEFAULT_STRING_SIZE_LIMIT = 8192

Defines a default length for a string buffer.

The default max. length of a string returned by a call to functions, which call the C-layer and need to pass an allocated string buffer to that function.

END_OF_LIST

const int END_OF_LIST = -1

A constant defining that property values will be read from an array property until the last value.

INVALID_ID

const int INVALID_ID = -1

A constant to check for an invalid ID returned from the property handling module.

Examples

Callback.c, CaptureToUserMemory.c, ContinuousCapture.c, and ContinuousCaptureGenICam.c.

PROP_MAX_VAL

const int PROP_MAX_VAL = -1

The index value to query the maximum value defined for this property.

Examples

ContinuousCapture.c, and ContinuousCaptureGenICam.c.

PROP_MIN_VAL

const int PROP_MIN_VAL = -2

The index value to query the minimum value defined for this property.

Examples

ContinuousCapture.c.

PROP_STEP_WIDTH

const int PROP_STEP_WIDTH = -3

The index value to query the step width value defined for this property.

ROOT_LIST

const int ROOT_LIST = 0

A constant defining the unique identifier for the root component list containing all other lists.

smIgnoreLists

const unsigned int smIgnoreLists = 0x2

When set lists are not taken into account during a search.

When this flag is set list objects will not be taken into account during a search for a component.

smIgnoreMethods

const unsigned int smIgnoreMethods = 0x4

When set method objects are not taken into account during a search.

When this flag is set method objects will not be taken into account during a search for a component.

smIgnoreProperties

const unsigned int smIgnoreProperties = 0x8

When set property objects are not taken into account during a search.

When this flag is set property objects will not be taken into account during a search for a component.