PropertyMap Class Reference

Represents the property interface of a component, usually a video capture device. More...

Public Member Functions

PropertyMap ()=default

Creates an invalid property map.

bool is_valid () const noexcept

Checks whether this property map is a valid object.

Property operator[] (const char *prop_name) const

Finds the property with a specified name in the property map.

Property operator[] (const std::string &prop_name) const

Finds the property with a specified name in the property map.

PropInteger operator[] (const PropId::PropIdInteger &integer_id) const

Finds the integer property specified by the given property id in the property map.

PropFloat operator[] (const PropId::PropIdFloat &float_id) const

Finds the float property specified by the given property id in the property map.

PropCommand operator[] (const PropId::PropIdCommand &command_id) const

Finds the command property specified by the given property id in the property map.

PropEnumeration operator[] (const PropId::PropIdEnumeration &enumeration_id) const

Finds the enumeration property specified by the given property id in the property map.

PropBoolean operator[] (const PropId::PropIdBoolean &boolean_id) const

Finds the boolean property specified by the given property id in the property map.

PropString operator[] (const PropId::PropIdString &string_id) const

Finds the string property specified by the given property id in the property map.

PropRegister operator[] (const PropId::PropIdRegister &register_id) const

Finds the register property specified by the given property id in the property map.

std::vector< Propertyall (Error &err=Error::Default()) const

Returns a list of all properties reachable from the property map's "Root" category.

bool executeCommand (const char *cmd_name, Error &err=Error::Default())

Executes a command with a known name.

bool executeCommand (const std::string &cmd_name, Error &err=Error::Default())

Executes a command with a known name.

bool executeCommand (const PropId::PropIdCommand &command_id, Error &err=Error::Default())

Executes a command with a specified identifier.

bool setValue (const char *integer_name, int64_t value, Error &err=Error::Default())

Set the value of a property with a known name to the passed integer value.

bool setValue (const std::string &integer_name, int64_t value, Error &err=Error::Default())

Set the value of a property with a known name to the passed integer value.

bool setValue (const PropId::PropIdInteger &integer_id, int64_t value, Error &err=Error::Default())

Set the value of an integer property with specified identifier to the passed integer value.

bool setValue (const char *float_name, double value, Error &err=Error::Default())

Set the value of a property with a known name to the passed double value.

bool setValue (const std::string &float_name, double value, Error &err=Error::Default())

Set the value of a property with a known name to the passed double value.

bool setValue (const PropId::PropIdFloat &float_id, double value, Error &err=Error::Default())

Set the value of a float property with specified identifier to the passed double value.

bool setValue (const char *boolean_name, bool value, Error &err=Error::Default())

Set the value of a property with a known name to the passed bool value.

bool setValue (const std::string &boolean_name, bool value, Error &err=Error::Default())

Set the value of a property with a known name to the passed bool value.

bool setValue (const PropId::PropIdBoolean &boolean_id, bool value, Error &err=Error::Default())

Set the value of a boolean property with specified identifier to the passed bool value.

bool setValue (const PropId::PropIdEnumeration &enumeration_id, bool value, Error &err=Error::Default())

Selects an entry in the enumeration property with specified identifier matching the passed bool value.

bool setValue (const char *string_name, const char *value, Error &err=Error::Default())

Set the value of a property with a known name to the passed string value.

bool setValue (const std::string &string_name, const std::string &value, Error &err=Error::Default())

Set the value of a property with a known name to the passed string value.

bool setValue (const PropId::PropIdString &string_id, const char *value, Error &err=Error::Default())

Set the value of a string property with a specified identifier to the passed string value.

bool setValue (const PropId::PropIdEnumeration &enumeration_id, const char *value, Error &err=Error::Default())

Set the value of an enumeration property with a specified identifier to the passed string value.

bool setValue (const PropId::PropIdBoolean &boolean_id, const char *value, Error &err=Error::Default())

Set the value of a boolean property with a specified identifier to the passed string value.

int64_t getValueInt64 (const char *prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as an integer.

double getValueDouble (const char *prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a double.

bool getValueBool (const char *prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a bool.

std::string getValueString (const char *prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a string.

int64_t getValueInt64 (const std::string &prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as an integer.

double getValueDouble (const std::string &prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a double.

bool getValueBool (const std::string &prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a bool.

std::string getValueString (const std::string &prop_name, Error &err=Error::Default()) const

Get the value of a property with a known name interpreted as a string.

int64_t getValueInt64 (const PropId::PropIdInteger &integer_id, Error &err=Error::Default()) const

Get the value of an integer property with a known name.

int64_t getValueInt64 (const PropId::PropIdBoolean &boolean_id, Error &err=Error::Default()) const

Get the value of a boolean property with a known name interpreted as an integer.

double getValueDouble (const PropId::PropIdFloat &float_id, Error &err=Error::Default()) const

Get the value of a float property with a known name.

double getValueDouble (const PropId::PropIdInteger &integer_id, Error &err=Error::Default()) const

Get the value of an integer property with a known name interpreted as a double.

bool getValueBool (const PropId::PropIdBoolean &boolean_id, Error &err=Error::Default()) const

Get the value of a boolean property with a known name.

bool getValueBool (const PropId::PropIdEnumeration &enumeration_id, Error &err=Error::Default()) const

Get the value of an enumeration property with a known name interpreted as bool.

std::string getValueString (const PropId::PropIdString &string_id, Error &err=Error::Default()) const

Get the value of a string property with a known name.

std::string getValueString (const PropId::PropIdEnumeration &enumeration_id, Error &err=Error::Default()) const

Get the value of an enumeration property with a known name.

std::string getValueString (const PropId::PropIdBoolean &boolean_id, Error &err=Error::Default()) const

Get a string representation of the value of a boolean property with a known name.

std::string getValueString (const PropId::PropIdInteger &integer_id, Error &err=Error::Default()) const

Get a string representation of the value of an integer property with a known name.

std::string getValueString (const PropId::PropIdFloat &float_id, Error &err=Error::Default()) const

Get a string representation of the value of a float property with a known name.

Property find (const char *prop_name, Error &err=Error::Default()) const

Finds the property with a specified name in the property map.

Property find (const std::string &prop_name, Error &err=Error::Default()) const

Finds the property with a specified name in the property map.

PropCommand find (const PropId::PropIdCommand &command_id, Error &err=Error::Default()) const

Finds the command property with a specified identifier in the property map.

PropCommand findCommand (const std::string &command_name, Error &err=Error::Default()) const

Finds the command property with a specified name in the property map.

PropCommand findCommand (const char *command_name, Error &err=Error::Default()) const

Finds the command property with a specified name in the property map.

PropInteger find (const PropId::PropIdInteger &integer_id, Error &err=Error::Default()) const

Finds the integer property with a specified identifier in the property map.

PropInteger findInteger (const std::string &integer_name, Error &err=Error::Default()) const

Finds the integer property with a specified name in the property map.

PropInteger findInteger (const char *integer_name, Error &err=Error::Default()) const

Finds the integer property with a specified name in the property map.

PropFloat find (const PropId::PropIdFloat &float_id, Error &err=Error::Default()) const

Finds the float property with a specified identifier in the property map.

PropFloat findFloat (const std::string &float_name, Error &err=Error::Default()) const

Finds the float property with a specified name in the property map.

PropFloat findFloat (const char *float_name, Error &err=Error::Default()) const

Finds the float property with a specified name in the property map.

PropBoolean find (const PropId::PropIdBoolean &boolean_id, Error &err=Error::Default()) const

Finds the boolean property with a specified identifier in the property map.

PropBoolean findBoolean (const std::string &boolean_name, Error &err=Error::Default()) const

Finds the boolean property with a specified name in the property map.

PropBoolean findBoolean (const char *boolean_name, Error &err=Error::Default()) const

Finds the boolean property with a specified name in the property map.

PropString find (const PropId::PropIdString &string_id, Error &err=Error::Default()) const

Finds the string property with a specified identifier in the property map.

PropString findString (const std::string &string_name, Error &err=Error::Default()) const

Finds the string property with a specified name in the property map.

PropString findString (const char *string_name, Error &err=Error::Default()) const

Finds the string property with a specified name in the property map.

PropEnumeration find (const PropId::PropIdEnumeration &enumeration_id, Error &err=Error::Default()) const

Finds the enumeration property with a specified identifier in the property map.

PropEnumeration findEnumeration (const std::string &enumeration_name, Error &err=Error::Default()) const

Finds the enumeration property with a specified name in the property map.

PropEnumeration findEnumeration (const char *enumeration_name, Error &err=Error::Default()) const

Finds the enumeration property with a specified name in the property map.

PropRegister find (const PropId::PropIdRegister &register_id, Error &err=Error::Default()) const

Finds the register property with a specified identifier in the property map.

PropRegister findRegister (const std::string &register_name, Error &err=Error::Default()) const

Finds the register property with a specified name in the property map.

PropRegister findRegister (const char *register_name, Error &err=Error::Default()) const

Finds the register property with a specified name in the property map.

PropCategory findCategory (const std::string &category_name, Error &err=Error::Default()) const

Finds the category property with a specified name in the property map.

PropCategory findCategory (const char *category_name, Error &err=Error::Default()) const

Finds the category property with a specified name in the property map.

bool connectChunkData (const std::shared_ptr< ic4::ImageBuffer > &image_buffer, Error &err=Error::Default())

Enables the use of the chunk data in the passed ImageBuffer as a backend for chunk properties in the property map.

bool serialize (std::vector< uint8_t > &buffer, Error &err=Error::Default()) const

Saves the state of the properties in this property map in a memory buffer.

bool serialize (const std::string &file_path, Error &err=Error::Default()) const

Saves the state of the properties in this property map into a file.

bool deSerialize (const std::vector< uint8_t > &buffer, Error &err=Error::Default())

Restores the state of the properties in this property map from a memory buffer containing data that was previously written by PropertyMap::serialize().

bool deSerialize (const std::string &file_path, Error &err=Error::Default())

Restores the state of the properties in this property map from a file that was previously written by PropertyMap::serialize().

Detailed Description

Represents the property interface of a component, usually a video capture device.

A property map offers quick access to known properties as well as functions to enumerate all features through the category tree.

There is a plethora of overloaded functions to access properties with a known name and type. For example, to find a known integer property, use:

To find a property with a known name, but unknown type, use one of the untyped functions:

Property values for known properties can also be set directly, for example by calling:

Additionally, property values for known properties can be queried directly, for example by calling:

To get a flat list of all properties in the property map's category tree, call PropertyMap::all().

The current values of all properties in a property map can be saved to a file or a memory buffer using PropertyMap::serialize(). To restore the settings at a later time, call PropertyMap::deSerialize().

An image buffer containing chunk data can be connected to a property map using PropertyMap::connectChunkData(). Doing so lets the property map uses the image buffer as the data source for chunk property read operations.

PropertyMap instances are created by their respective component when queried, for example by calling Grabber::devicePropertyMap() or VideoWriter::propertyMap().

When a function creating a property map fails, or the default constructor is used, an invalid object is created. For invalid objects, PropertyMap::is_valid() will return false, and all other member functions will fail.

PropertyMap objects are copyable.

Member Function Documentation

◆ all()

std::vector< Property > all ( Error err = Error::Default()) const
inline

Returns a list of all properties reachable from the property map's "Root" category.

Parameters
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::vector containing all properties in the property map.
If an error occurred, the function returns an empty vector. Check the err output parameter for details.

◆ connectChunkData()

bool connectChunkData ( const std::shared_ptr< ic4::ImageBuffer > &  image_buffer,
Error err = Error::Default() 
)
inline

Enables the use of the chunk data in the passed ImageBuffer as a backend for chunk properties in the property map.

Parameters
[in]image_bufferAn image buffer with chunk data.
This parameter may be nullptr to disconnect the previously connected buffer.
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.
Remarks
The property map takes a reference to the passed image buffer, extending its lifetime and preventing automatic reuse. The reference is released when a new image buffer is connected to the property map, or nullptr is passed in the image_buffer argument.

◆ deSerialize() [1/2]

bool deSerialize ( const std::string &  file_path,
Error err = Error::Default() 
)
inline

Restores the state of the properties in this property map from a file that was previously written by PropertyMap::serialize().

Parameters
[in]file_pathPath to a file containing the serialized property data
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.
See also
PropertyMap::serialize(const std::string&, Error&) const

◆ deSerialize() [2/2]

bool deSerialize ( const std::vector< uint8_t > &  buffer,
Error err = Error::Default() 
)
inline

Restores the state of the properties in this property map from a memory buffer containing data that was previously written by PropertyMap::serialize().

Parameters
[in]bufferA std::vector containing the serialized property data
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.
See also
PropertyMap::serialize(std::vector<uint8_t>&, Error&) const

◆ executeCommand() [1/3]

bool executeCommand ( const char *  cmd_name,
Error err = Error::Default() 
)
inline

Executes a command with a known name.

Parameters
[in]cmd_nameName of a command property in this property map
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ executeCommand() [2/3]

bool executeCommand ( const PropId::PropIdCommand command_id,
Error err = Error::Default() 
)
inline

Executes a command with a specified identifier.

Parameters
[in]command_idIdentifier of a command property in this property map
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ executeCommand() [3/3]

bool executeCommand ( const std::string &  cmd_name,
Error err = Error::Default() 
)
inline

Executes a command with a known name.

Parameters
[in]cmd_nameName of a command property in this property map
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ find() [1/9]

Property find ( const char *  prop_name,
Error err = Error::Default() 
) const
inline

Finds the property with a specified name in the property map.

Parameters
[in]prop_nameThe name of the property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [2/9]

PropBoolean find ( const PropId::PropIdBoolean boolean_id,
Error err = Error::Default() 
) const
inline

Finds the boolean property with a specified identifier in the property map.

Parameters
[in]boolean_idThe identifier of the boolean property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [3/9]

PropCommand find ( const PropId::PropIdCommand command_id,
Error err = Error::Default() 
) const
inline

Finds the command property with a specified identifier in the property map.

Parameters
[in]command_idThe identifier of the command property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [4/9]

PropEnumeration find ( const PropId::PropIdEnumeration enumeration_id,
Error err = Error::Default() 
) const
inline

Finds the enumeration property with a specified identifier in the property map.

Parameters
[in]enumeration_idThe identifier of the enumeration property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [5/9]

PropFloat find ( const PropId::PropIdFloat float_id,
Error err = Error::Default() 
) const
inline

Finds the float property with a specified identifier in the property map.

Parameters
[in]float_idThe identifier of the float property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [6/9]

PropInteger find ( const PropId::PropIdInteger integer_id,
Error err = Error::Default() 
) const
inline

Finds the integer property with a specified identifier in the property map.

Parameters
[in]integer_idThe identifier of the integer property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [7/9]

PropRegister find ( const PropId::PropIdRegister register_id,
Error err = Error::Default() 
) const
inline

Finds the register property with a specified identifier in the property map.

Parameters
[in]register_idThe identifier of the register property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [8/9]

PropString find ( const PropId::PropIdString string_id,
Error err = Error::Default() 
) const
inline

Finds the string property with a specified identifier in the property map.

Parameters
[in]string_idThe identifier of the string property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name matches identifier.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ find() [9/9]

Property find ( const std::string &  prop_name,
Error err = Error::Default() 
) const
inline

Finds the property with a specified name in the property map.

Parameters
[in]prop_nameThe name of the property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findBoolean() [1/2]

PropBoolean findBoolean ( const char *  boolean_name,
Error err = Error::Default() 
) const
inline

Finds the boolean property with a specified name in the property map.

Parameters
[in]boolean_nameThe name of the boolean property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findBoolean() [2/2]

PropBoolean findBoolean ( const std::string &  boolean_name,
Error err = Error::Default() 
) const
inline

Finds the boolean property with a specified name in the property map.

Parameters
[in]boolean_nameThe name of the boolean property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findCategory() [1/2]

PropCategory findCategory ( const char *  category_name,
Error err = Error::Default() 
) const
inline

Finds the category property with a specified name in the property map.

Parameters
[in]category_nameThe name of the category property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findCategory() [2/2]

PropCategory findCategory ( const std::string &  category_name,
Error err = Error::Default() 
) const
inline

Finds the category property with a specified name in the property map.

Parameters
[in]category_nameThe name of the category property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findCommand() [1/2]

PropCommand findCommand ( const char *  command_name,
Error err = Error::Default() 
) const
inline

Finds the command property with a specified name in the property map.

Parameters
[in]command_nameThe name of the command property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findCommand() [2/2]

PropCommand findCommand ( const std::string &  command_name,
Error err = Error::Default() 
) const
inline

Finds the command property with a specified name in the property map.

Parameters
[in]command_nameThe name of the command property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findEnumeration() [1/2]

PropEnumeration findEnumeration ( const char *  enumeration_name,
Error err = Error::Default() 
) const
inline

Finds the enumeration property with a specified name in the property map.

Parameters
[in]enumeration_nameThe name of the enumeration property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findEnumeration() [2/2]

PropEnumeration findEnumeration ( const std::string &  enumeration_name,
Error err = Error::Default() 
) const
inline

Finds the enumeration property with a specified name in the property map.

Parameters
[in]enumeration_nameThe name of the enumeration property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findFloat() [1/2]

PropFloat findFloat ( const char *  float_name,
Error err = Error::Default() 
) const
inline

Finds the float property with a specified name in the property map.

Parameters
[in]float_nameThe name of the float property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findFloat() [2/2]

PropFloat findFloat ( const std::string &  float_name,
Error err = Error::Default() 
) const
inline

Finds the float property with a specified name in the property map.

Parameters
[in]float_nameThe name of the float property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findInteger() [1/2]

PropInteger findInteger ( const char *  integer_name,
Error err = Error::Default() 
) const
inline

Finds the integer property with a specified name in the property map.

Parameters
[in]integer_nameThe name of the integer property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findInteger() [2/2]

PropInteger findInteger ( const std::string &  integer_name,
Error err = Error::Default() 
) const
inline

Finds the integer property with a specified name in the property map.

Parameters
[in]integer_nameThe name of the integer property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findRegister() [1/2]

PropRegister findRegister ( const char *  register_name,
Error err = Error::Default() 
) const
inline

Finds the register property with a specified name in the property map.

Parameters
[in]register_nameThe name of the register property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findRegister() [2/2]

PropRegister findRegister ( const std::string &  register_name,
Error err = Error::Default() 
) const
inline

Finds the register property with a specified name in the property map.

Parameters
[in]register_nameThe name of the register property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findString() [1/2]

PropString findString ( const char *  string_name,
Error err = Error::Default() 
) const
inline

Finds the string property with a specified name in the property map.

Parameters
[in]string_nameThe name of the string property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ findString() [2/2]

PropString findString ( const std::string &  string_name,
Error err = Error::Default() 
) const
inline

Finds the string property with a specified name in the property map.

Parameters
[in]string_nameThe name of the string property to find
[out]errReference to an error handler. See Error Handling for details.
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid() or the err output parameter.

◆ getValueBool() [1/4]

bool getValueBool ( const char *  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a bool.

The behavior depends on the type of the property:

  • For boolean properties, the value is returned directly.
  • For enumeration properties, a value is returned if the name of the currently selected entry unambiguously suggests to represent true or false.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueBool() [2/4]

bool getValueBool ( const PropId::PropIdBoolean boolean_id,
Error err = Error::Default() 
) const
inline

Get the value of a boolean property with a known name.

Parameters
[in]boolean_idId of a boolean property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueBool() [3/4]

bool getValueBool ( const PropId::PropIdEnumeration enumeration_id,
Error err = Error::Default() 
) const
inline

Get the value of an enumeration property with a known name interpreted as bool.

A boolean value is returned if the name of the currently selected entry unambiguously suggests to represent true or false.

Parameters
[in]enumeration_idId of an enumeration property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueBool() [4/4]

bool getValueBool ( const std::string &  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a bool.

The behavior depends on the type of the property:

  • For boolean properties, the value is returned directly.
  • For enumeration properties, a value is returned if the name of the currently selected entry unambiguously suggests to represent true or false.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueDouble() [1/4]

double getValueDouble ( const char *  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a double.

The behavior depends on the type of the property:

  • For integer properties, the value is converted to double.
  • For float properties, the value is returned directly.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueDouble() [2/4]

double getValueDouble ( const PropId::PropIdFloat float_id,
Error err = Error::Default() 
) const
inline

Get the value of a float property with a known name.

Parameters
[in]float_idId of a float property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueDouble() [3/4]

double getValueDouble ( const PropId::PropIdInteger integer_id,
Error err = Error::Default() 
) const
inline

Get the value of an integer property with a known name interpreted as a double.

Parameters
[in]integer_idId of an integer property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueDouble() [4/4]

double getValueDouble ( const std::string &  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a double.

The behavior depends on the type of the property:

  • For integer properties, the value is converted to double.
  • For float properties, the value is returned directly.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueInt64() [1/4]

int64_t getValueInt64 ( const char *  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as an integer.

The behavior depends on the type of the property:

  • For integer properties, the value is returned directly.
  • For boolean properties, the value returned is 1 or 0.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueInt64() [2/4]

int64_t getValueInt64 ( const PropId::PropIdBoolean boolean_id,
Error err = Error::Default() 
) const
inline

Get the value of a boolean property with a known name interpreted as an integer.

The value returned is 1 or 0.

Parameters
[in]boolean_idId of a boolean property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueInt64() [3/4]

int64_t getValueInt64 ( const PropId::PropIdInteger integer_id,
Error err = Error::Default() 
) const
inline

Get the value of an integer property with a known name.

Parameters
[in]integer_idId of an integer property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueInt64() [4/4]

int64_t getValueInt64 ( const std::string &  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as an integer.

The behavior depends on the type of the property:

  • For integer properties, the value is returned directly.
  • For boolean properties, the value returned is 1 or 0.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [1/7]

std::string getValueString ( const char *  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a string.

The behavior depends on the type of the property:

  • For integer properties, the value is converted to a string
  • For float properties, the value is converted to a string
  • For boolean properties, the value is converted to the string "true" or "false".
  • For enumeration properties, the name of the currently selected entry is returned.
  • For string properties, the value is returned directly.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [2/7]

std::string getValueString ( const PropId::PropIdBoolean boolean_id,
Error err = Error::Default() 
) const
inline

Get a string representation of the value of a boolean property with a known name.

The returned string is either "true" or "false".

Parameters
[in]boolean_idId of a boolean property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [3/7]

std::string getValueString ( const PropId::PropIdEnumeration enumeration_id,
Error err = Error::Default() 
) const
inline

Get the value of an enumeration property with a known name.

Parameters
[in]enumeration_idId of an enumeration property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [4/7]

std::string getValueString ( const PropId::PropIdFloat float_id,
Error err = Error::Default() 
) const
inline

Get a string representation of the value of a float property with a known name.

Parameters
[in]float_idId of a float property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [5/7]

std::string getValueString ( const PropId::PropIdInteger integer_id,
Error err = Error::Default() 
) const
inline

Get a string representation of the value of an integer property with a known name.

Parameters
[in]integer_idId of an integer property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [6/7]

std::string getValueString ( const PropId::PropIdString string_id,
Error err = Error::Default() 
) const
inline

Get the value of a string property with a known name.

Parameters
[in]string_idId of a string property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ getValueString() [7/7]

std::string getValueString ( const std::string &  prop_name,
Error err = Error::Default() 
) const
inline

Get the value of a property with a known name interpreted as a string.

The behavior depends on the type of the property:

  • For integer properties, the value is converted to a string
  • For float properties, the value is converted to a string
  • For boolean properties, the value is converted to the string "true" or "false".
  • For enumeration properties, the name of the currently selected entry is returned.
  • For string properties, the value is returned directly.
  • For all other property types, the call results in an error (ErrorCode::GenICamTypeMismatch).
Parameters
[in]prop_nameName of a property inside map
[out]errReference to an error handler. See Error Handling for details.
Returns
If successful, the value of the property is returned. The return value is undefined in case of an error.
Always check use err output parameter or enable exceptions to detect possible errors.

◆ is_valid()

bool is_valid ( ) const
inlinenoexcept

Checks whether this property map is a valid object.

If there is an error in the function creating this property map and function was not configured to throw on error, or the default constructor is used, an invalid object is created. All member function calls will fail.

Returns
true, if this property object was constructed successfully, otherwise false.
In case of an error, check the creating function's error parameter for details.
See also
Error Handling

◆ operator[]() [1/9]

Property operator[] ( const char *  prop_name) const
inline

Finds the property with a specified name in the property map.

Parameters
[in]prop_nameThe name of the property to find
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [2/9]

PropBoolean operator[] ( const PropId::PropIdBoolean boolean_id) const
inline

Finds the boolean property specified by the given property id in the property map.

Parameters
[in]boolean_idIdentifier of the property to find
Returns
The boolean property matching boolean_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [3/9]

PropCommand operator[] ( const PropId::PropIdCommand command_id) const
inline

Finds the command property specified by the given property id in the property map.

Parameters
[in]command_idIdentifier of the property to find
Returns
The float property matching command_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [4/9]

PropEnumeration operator[] ( const PropId::PropIdEnumeration enumeration_id) const
inline

Finds the enumeration property specified by the given property id in the property map.

Parameters
[in]enumeration_idIdentifier of the property to find
Returns
The enumeration property matching enumeration_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [5/9]

PropFloat operator[] ( const PropId::PropIdFloat float_id) const
inline

Finds the float property specified by the given property id in the property map.

Parameters
[in]float_idIdentifier of the property to find
Returns
The float property matching float_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [6/9]

PropInteger operator[] ( const PropId::PropIdInteger integer_id) const
inline

Finds the integer property specified by the given property id in the property map.

Parameters
[in]integer_idIdentifier of the property to find
Returns
The integer property matching integer_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [7/9]

PropRegister operator[] ( const PropId::PropIdRegister register_id) const
inline

Finds the register property specified by the given property id in the property map.

Parameters
[in]register_idIdentifier of the property to find
Returns
The register property matching register_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [8/9]

PropString operator[] ( const PropId::PropIdString string_id) const
inline

Finds the string property specified by the given property id in the property map.

Parameters
[in]string_idIdentifier of the property to find
Returns
The string property matching string_id.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ operator[]() [9/9]

Property operator[] ( const std::string &  prop_name) const
inline

Finds the property with a specified name in the property map.

Parameters
[in]prop_nameThe name of the property to find
Returns
The property whose name is equal to prop_name.
If no matching property is found, an invalid property object is returned. Check Property::is_valid().
Remarks
This operator implicitly uses the default error handler (Error::Default()) and will throw IC4Exception in case of an error, if the default error handler was configured to do so.

◆ serialize() [1/2]

bool serialize ( const std::string &  file_path,
Error err = Error::Default() 
) const
inline

Saves the state of the properties in this property map into a file.

Parameters
[in]file_pathA path to a file that the property state is written to
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.
See also
PropertyMap::deSerialize(const std::string&, Error&)

◆ serialize() [2/2]

bool serialize ( std::vector< uint8_t > &  buffer,
Error err = Error::Default() 
) const
inline

Saves the state of the properties in this property map in a memory buffer.

Parameters
[out]bufferA reference to a std::vector to receive the serialized property data
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.
See also
PropertyMap::deSerialize(const std::vector<uint8_t>&, Error&)

◆ setValue() [1/15]

bool setValue ( const char *  boolean_name,
bool  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed bool value.

The behavior depends on the type of the property:

  • For boolean properties, the value is set directly.
  • For enumeration properties, it selects the entry with a name that unambiguously suggests to represent true or false, if available.
  • For command properties, the command is executed if value is true.
  • For all other property types, the call results in an error.
Parameters
[in]boolean_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [2/15]

bool setValue ( const char *  float_name,
double  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed double value.

The behavior depends on the type of the property:

  • For integer properties, the value is rounded to the nearest integer.
  • For float properties, the value is set directly.
  • For all other property types, the call results in an error.
Parameters
[in]float_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [3/15]

bool setValue ( const char *  integer_name,
int64_t  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed integer value.

The behavior depends on the type of the property:

  • For integer properties, the value is set directly.
  • For float properties, the value is set directly.
  • For boolean properties, if the value is 1 or 0, it is set to true or false respectively. Other values result in an error.
  • For enumeration properties, the value is set if the property is "PixelFormat".
  • For command properties, the command is executed if value is 1.
  • For all other property types, the call results in an error.
Parameters
[in]integer_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [4/15]

bool setValue ( const char *  string_name,
const char *  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed string value.

The behavior depends on the type of the property:

  • For integer properties, the string is parsed, and the found integer value is set.
  • For float properties, the string is parsed, and the found floating-point value is set.
  • For boolean properties, a value is set if the string can be unambiguously identified to represent true or false.
  • For enumeration properties, the entry with a name or display name matching the value is selected.
  • For string properties, the value is set directly.
  • For command properties, the command is executed if value is "1", "true" or "execute".
  • For all other property types, the call results in an error.
Parameters
[in]string_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [5/15]

bool setValue ( const PropId::PropIdBoolean boolean_id,
bool  value,
Error err = Error::Default() 
)
inline

Set the value of a boolean property with specified identifier to the passed bool value.

Parameters
[in]boolean_idIdentifier of a boolean property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [6/15]

bool setValue ( const PropId::PropIdBoolean boolean_id,
const char *  value,
Error err = Error::Default() 
)
inline

Set the value of a boolean property with a specified identifier to the passed string value.

The value is set if the string can be unambiguously identified to represent true or false.

Parameters
boolean_idIdentifier of a boolean property in this property map
valueNew value to be set
errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [7/15]

bool setValue ( const PropId::PropIdEnumeration enumeration_id,
bool  value,
Error err = Error::Default() 
)
inline

Selects an entry in the enumeration property with specified identifier matching the passed bool value.

An entry is only selected if there is an entry with a name that unambiguously suggests to represent true or false.

Parameters
enumeration_idIdentifier of an enumeration property in this property map
valueNew value to be set
errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [8/15]

bool setValue ( const PropId::PropIdEnumeration enumeration_id,
const char *  value,
Error err = Error::Default() 
)
inline

Set the value of an enumeration property with a specified identifier to the passed string value.

The entry with a name matching the passed value is selected.

Parameters
[in]enumeration_idIdentifier of an enumeration property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [9/15]

bool setValue ( const PropId::PropIdFloat float_id,
double  value,
Error err = Error::Default() 
)
inline

Set the value of a float property with specified identifier to the passed double value.

Parameters
[in]float_idIdentifier of a float property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [10/15]

bool setValue ( const PropId::PropIdInteger integer_id,
int64_t  value,
Error err = Error::Default() 
)
inline

Set the value of an integer property with specified identifier to the passed integer value.

Parameters
[in]integer_idIdentifier of an integer property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [11/15]

bool setValue ( const PropId::PropIdString string_id,
const char *  value,
Error err = Error::Default() 
)
inline

Set the value of a string property with a specified identifier to the passed string value.

Parameters
[in]string_idIdentifier of a string property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [12/15]

bool setValue ( const std::string &  boolean_name,
bool  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed bool value.

The behavior depends on the type of the property:

  • For boolean properties, the value is set directly.
  • For enumeration properties, it selects the entry with a name that unambiguously suggests to represent true or false, if available.
  • For command properties, the command is executed if value is true.
  • For all other property types, the call results in an error.
Parameters
[in]boolean_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [13/15]

bool setValue ( const std::string &  float_name,
double  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed double value.

The behavior depends on the type of the property:

  • For integer properties, the value is rounded to the nearest integer.
  • For float properties, the value is set directly.
  • For all other property types, the call results in an error.
Parameters
[in]float_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [14/15]

bool setValue ( const std::string &  integer_name,
int64_t  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed integer value.

The behavior depends on the type of the property:

  • For integer properties, the value is set directly.
  • For float properties, the value is set directly.
  • For boolean properties, if the value is 1 or 0, it is set to true or false respectively. Other values result in an error.
  • For enumeration properties, the value is set if the property is "PixelFormat".
  • For command properties, the command is executed if value is 1.
  • For all other property types, the call results in an error.
Parameters
[in]integer_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ setValue() [15/15]

bool setValue ( const std::string &  string_name,
const std::string &  value,
Error err = Error::Default() 
)
inline

Set the value of a property with a known name to the passed string value.

The behavior depends on the type of the property:

  • For integer properties, the string is parsed, and the found integer value is set
  • For float properties, the string is parsed, and the found floating-point value is set
  • For boolean properties, a value is set if the string can be unambiguously identified to represent true or false.
  • For enumeration properties, the entry with a name or display name matching the value is set.
  • For string properties, the value is set directly.
  • For command properties, the command is executed if value is "1", "true" or "execute".
  • For all other property types, the call results in an error.
Parameters
[in]string_nameName of a property in this property map
[in]valueNew value to be set
[out]errReference to an error handler. See Error Handling for details.
Returns
true on success, otherwise false.
Check the err output parameter for error code and error message.