Property Objects

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

Modules

	Category Properties Category properties define a tree-relationship between all properties in a property map.
	Command Properties Command properties represent an action that can be performed by the device.
	Integer Properties Integer properties represent a feature whose value is an integer number.
	Float Properties Float properties represent a feature whose value is a floating-point number.
	Boolean Properties Boolean properties represent a feature whose value is a simple on/off switch.
	String Properties String properties represent features whole value is a text.
	Enumeration Properties Enumeration properties represent a feature whose value is selected from a list of named entries.
	Register Properties Register properties have a value represented by raw bytes.

Data Structures

struct

IC4_PROPERTY

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

Typedefs

typedef void(*	ic4_prop_notification) (struct IC4_PROPERTY prop, void user_ptr) Property notification handler function pointer.
typedef void(*	ic4_prop_notification_deleter) (void *user_ptr) Property notification deleter.

Enumerations

enum	IC4_PROPERTY_TYPE { IC4_PROPTYPE_INVALID , IC4_PROPTYPE_INTEGER , IC4_PROPTYPE_FLOAT , IC4_PROPTYPE_ENUMERATION , IC4_PROPTYPE_BOOLEAN , IC4_PROPTYPE_STRING , IC4_PROPTYPE_COMMAND , IC4_PROPTYPE_CATEGORY , IC4_PROPTYPE_REGISTER , IC4_PROPTYPE_PORT , IC4_PROPTYPE_ENUMENTRY } Defines the possible property types. More...
enum	IC4_PROPERTY_VISIBILITY { IC4_PROPVIS_BEGINNER , IC4_PROPVIS_EXPERT , IC4_PROPVIS_GURU , IC4_PROPVIS_INVISIBLE } Defines the possible property visibilities. More...
enum	IC4_PROPERTY_INCREMENT_MODE { IC4_PROPINCMODE_INCREMENT , IC4_PROPINCMODE_VALUESET , IC4_PROPINCMODE_NONE } Defines the possible property increment modes for Integer and Float properties. More...

Functions

struct IC4_PROPERTY *	ic4_prop_ref (struct IC4_PROPERTY *prop) Increases the property's internal reference count by one.
void	ic4_prop_unref (struct IC4_PROPERTY *prop) Decreases the property's internal reference count by one.
enum IC4_PROPERTY_TYPE	ic4_prop_get_type (struct IC4_PROPERTY *prop) Returns the type of the passed property.
const char *	ic4_prop_get_name (struct IC4_PROPERTY *prop) Returns the name of the passed property.
bool	ic4_prop_is_available (struct IC4_PROPERTY *prop) Checks whether a property is currently available.
bool	ic4_prop_is_locked (struct IC4_PROPERTY *prop) Checks whether a property is currently locked.
bool	ic4_prop_is_likely_locked_by_stream (struct IC4_PROPERTY *prop) Tries to determine whether a property is locked because a data stream is active.
bool	ic4_prop_is_readonly (struct IC4_PROPERTY *prop) Checks whether a property is read-only.
enum IC4_PROPERTY_VISIBILITY	ic4_prop_get_visibility (struct IC4_PROPERTY *prop) Returns a visibility hint for the property.
const char *	ic4_prop_get_display_name (struct IC4_PROPERTY *prop) Returns the display name of the passed property.
const char *	ic4_prop_get_tooltip (struct IC4_PROPERTY *prop) Returns a tooltip for the passed property.
const char *	ic4_prop_get_description (struct IC4_PROPERTY *prop) Returns a description text for the passed property.
bool	ic4_prop_event_add_notification (struct IC4_PROPERTY prop, ic4_prop_notification handler, void user_ptr, ic4_prop_notification_deleter deleter) Registers a property notification handler.
bool	ic4_prop_event_remove_notification (struct IC4_PROPERTY prop, ic4_prop_notification handler, void user_ptr) Unregisters a previously registered notification handler.
bool	ic4_prop_is_selector (struct IC4_PROPERTY *prop) Indicates whether this property's value changes the meaning and/or value of other properties.
bool	ic4_prop_get_selected_props (struct IC4_PROPERTY prop, struct IC4_PROPERTY_LIST *ppSelected) Returns the list of properties whose values' meaning depend on this property.

Detailed Description

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

Typedef Documentation

◆ ic4_prop_notification

typedef void(* ic4_prop_notification) (struct IC4_PROPERTY *prop, void *user_ptr)

Property notification handler function pointer.

Parameters

[in]	prop	The property that has changed
[in]	user_ptr	The user data that was specified when the notification handler was registered

See also: ic4_prop_event_add_notification

◆ ic4_prop_notification_deleter

typedef void(* ic4_prop_notification_deleter) (void *user_ptr)

Property notification deleter.

Parameters

[in] user_ptr The user data that was specified when the notification deleter was registered

See also: ic4_prop_event_add_notification; ic4_prop_event_remove_notification

Enumeration Type Documentation

◆ IC4_PROPERTY_INCREMENT_MODE

enum IC4_PROPERTY_INCREMENT_MODE

Defines the possible property increment modes for Integer and Float properties.

Enumerator

Enumerator
IC4_PROPINCMODE_INCREMENT	The property used a fixed step between valid values. Use ic4_prop_integer_get_inc() or ic4_prop_float_get_inc() to get the property's step size.
IC4_PROPINCMODE_VALUESET	The property defines a set of valid values. Use ic4_prop_integer_get_valid_value_set() or ic4_prop_float_get_valid_value_set() to query the set of valid values.
IC4_PROPINCMODE_NONE	The property allows setting all values between its minimum and maximum value. This mode is only valid for Float properties. Integer properties report increment 1 if they want to allow every possible value between their minimum and maximum value.

IC4_PROPINCMODE_INCREMENT

The property used a fixed step between valid values.

Use ic4_prop_integer_get_inc() or ic4_prop_float_get_inc() to get the property's step size.

IC4_PROPINCMODE_VALUESET

The property defines a set of valid values.

Use ic4_prop_integer_get_valid_value_set() or ic4_prop_float_get_valid_value_set() to query the set of valid values.

IC4_PROPINCMODE_NONE

The property allows setting all values between its minimum and maximum value.

This mode is only valid for Float properties.

Integer properties report increment 1 if they want to allow every possible value between their minimum and maximum value.

◆ IC4_PROPERTY_TYPE

enum IC4_PROPERTY_TYPE

Defines the possible property types.

The property type defines the possible operations on a property and its data type.

Enumerator
IC4_PROPTYPE_INVALID	Not a valid property type, indicates an error.
IC4_PROPTYPE_INTEGER	Integer property.
IC4_PROPTYPE_FLOAT	Float property.
IC4_PROPTYPE_ENUMERATION	Enumeration property.
IC4_PROPTYPE_BOOLEAN	Boolean property.
IC4_PROPTYPE_STRING	String property.
IC4_PROPTYPE_COMMAND	Command property.
IC4_PROPTYPE_CATEGORY	Category property.
IC4_PROPTYPE_REGISTER	Register property.
IC4_PROPTYPE_PORT	Port property.
IC4_PROPTYPE_ENUMENTRY	Enumeration entry property.

◆ IC4_PROPERTY_VISIBILITY

enum IC4_PROPERTY_VISIBILITY

Defines the possible property visibilities.

Each property has a visibility hint that can be used to create user interfaces for different user types.

Enumerator
IC4_PROPVIS_BEGINNER	Beginner visibility.
IC4_PROPVIS_EXPERT	Expert visibility.
IC4_PROPVIS_GURU	Guru visibility.
IC4_PROPVIS_INVISIBLE	Invisible.

Function Documentation

◆ ic4_prop_event_add_notification()

bool ic4_prop_event_add_notification	(	struct IC4_PROPERTY *	prop,
		ic4_prop_notification	handler,
		void *	user_ptr,
		ic4_prop_notification_deleter	deleter
	)

Registers a property notification handler.

The property notification handler is called whenever an aspect of the property changes, for example its value or locked status.

Parameters

[in]	prop	A property
[in]	handler	The property notification handler to be called if prop changes
[in]	user_ptr	User data to be passed to the notification handler
[in]	deleter	The property notification deleter to be called if the notification is removed, or the property is destroyed

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: The deleter callback can useful to release resources that the caller passed in into user_ptr.; Multiple notification handlers can be registered for the same property, as long as the user_ptr parameter is different.

See also: ic4_prop_event_remove_notification; ic4_prop_notification; ic4_prop_notification_deleter

◆ ic4_prop_event_remove_notification()

bool ic4_prop_event_remove_notification	(	struct IC4_PROPERTY *	prop,
		ic4_prop_notification	handler,
		void *	user_ptr
	)

Unregisters a previously registered notification handler.

Parameters

[in]	prop	A property with a registered notification handler
[in]	handler	The property notification handler to be removed
[in]	user_ptr	The user data that was specified when the handler was registered

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: The values for handler and user_ptr must exactly match the arguments of the previous successful call to ic4_prop_event_add_notification().

See also: ic4_prop_event_add_notification

◆ ic4_prop_get_description()

const char * ic4_prop_get_description ( struct IC4_PROPERTY * prop )

Returns a description text for the passed property.

Parameters

[in] prop A property

Returns: The description for the passed property, or NULL in case of an error.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the property object exists.

Remarks: A property's description is a short text that describes the property, usually in more detail than the tooltip.

See also: ic4_prop_get_tooltip

◆ ic4_prop_get_display_name()

const char * ic4_prop_get_display_name ( struct IC4_PROPERTY * prop )

Returns the display name of the passed property.

Parameters

[in] prop A property

Returns: The display name of the passed property, or NULL in case of an error.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the property object exists.

Remarks: A property's display name is a text representation of the property that is meant to be displayed in user interfaces.
For example, the display name of the ExposureTime property usually is Exposure Time.

See also: ic4_prop_get_name

◆ ic4_prop_get_name()

const char * ic4_prop_get_name ( struct IC4_PROPERTY * prop )

Returns the name of the passed property.

Parameters

[in] prop A property

Returns: The name of the passed property, or NULL in case of an error.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the property object exists.

Remarks: A property's name is the symbolic name with which it can be found in a Property Map, for example ExposureTime or AcquisitionFrameRate.

See also: ic4_prop_get_display_name

◆ ic4_prop_get_selected_props()

bool ic4_prop_get_selected_props	(	struct IC4_PROPERTY *	prop,
		struct IC4_PROPERTY_LIST **	ppSelected
	)

Returns the list of properties whose values' meaning depend on this property.

Parameters

[in]	prop	A property that is a selector
[out]	ppSelected	A pointer to a property list receiving the list of properties selected by `prop`. When the property list is no longer required, release the object reference using ic4_proplist_unref().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: If prop is not a boolean property, the function fails and the error value is set to IC4_ERROR_GENICAM_TYPE_MISMATCH.

See also: ic4_prop_is_selector

◆ ic4_prop_get_tooltip()

const char * ic4_prop_get_tooltip ( struct IC4_PROPERTY * prop )

Returns a tooltip for the passed property.

Parameters

[in] prop A property

Returns: The tooltip for the passed property, or NULL in case of an error.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the property object exists.

Remarks: A property's tooltip is a text that can be used when a tooltip is required by a user interface.
Usually, the tooltip is a short description of the property.

See also: ic4_prop_get_description

◆ ic4_prop_get_type()

enum IC4_PROPERTY_TYPE ic4_prop_get_type ( struct IC4_PROPERTY * prop )

Returns the type of the passed property.

Parameters

[in] prop A property

Returns: The type of the property prop, or IC4_PROPTYPE_INVALID in case of an error.
Use ic4_get_last_error() to query error information.

See also: IC4_PROPERTY_TYPE

◆ ic4_prop_get_visibility()

enum IC4_PROPERTY_VISIBILITY ic4_prop_get_visibility ( struct IC4_PROPERTY * prop )

Returns a visibility hint for the property.

The visibility hint can be used to create user interfaces with different complexities. The most commonly used properties have the beginner visibility, while rarely used or diagnostic features might be tagged guru or even invisible.

Parameters

[in] prop A property

Returns: The visibility hint for the property.
If there is an error, this function returns IC4_PROPVIS_INVISIBLE. Use ic4_get_last_error() to query error information.

◆ ic4_prop_is_available()

bool ic4_prop_is_available ( struct IC4_PROPERTY * prop )

Checks whether a property is currently available.

If a property is not available, attempts to read or write its value will fail.

A property may become unavailable, if its value does not have a meaning in the current state of the device. The property's availability status can change upon writing to another property.

Parameters

[in] prop A property

Returns: true, if the property is currently available, otherwise false.
If there is an error, this function returns false. Use ic4_get_last_error() to query error information.

See also: ic4_prop_is_locked; ic4_prop_is_readonly

◆ ic4_prop_is_likely_locked_by_stream()

bool ic4_prop_is_likely_locked_by_stream ( struct IC4_PROPERTY * prop )

Tries to determine whether a property is locked because a data stream is active.

Parameters

[in] prop A property

Returns: true, if the property is currently locked, and will likely be unlocked if the data stream is stopped.
false, if the property is not currently locked, or stopping the data stream will probably not lead to the property being unlocked.
If there is an error, this function returns false. Use ic4_get_last_error() to query error information.

Remarks: For technical reasons, this function cannot always accurately predict the future.

See also: ic4_prop_is_locked

◆ ic4_prop_is_locked()

bool ic4_prop_is_locked ( struct IC4_PROPERTY * prop )

Checks whether a property is currently locked.

A locked property can be read, but attempts to write its value will fail.

A property's locked status may change upon writing to another property.

Common examples for locked properties are ExposureTime or Gain if ExposureAuto or GainAuto are enabled.

Parameters

[in] prop A property

Returns: true, if the property is currently locked, otherwise false.
If there is an error, this function returns false. Use ic4_get_last_error() to query error information.

See also: ic4_prop_is_available; ic4_prop_is_readonly; ic4_prop_is_likely_locked_by_stream

◆ ic4_prop_is_readonly()

bool ic4_prop_is_readonly ( struct IC4_PROPERTY * prop )

Checks whether a property is read-only.

A read-only property will never be writable, the read-only status will never change.

A Common examples for read-only property is DeviceTemperature.

Parameters

[in] prop A property

Returns: true, if the property is read-only, otherwise false.
If there is an error, this function returns false. Use ic4_get_last_error() to query error information.

See also: ic4_prop_is_available; ic4_prop_is_locked

◆ ic4_prop_is_selector()

bool ic4_prop_is_selector ( struct IC4_PROPERTY * prop )

Indicates whether this property's value changes the meaning and/or value of other properties.

Parameters

[in] prop A property

Returns: true, if prop is a selector, otherwise false.
If an error occurs, the function returns false. Use ic4_get_last_error() to query error information.

See also: ic4_prop_get_selected

◆ ic4_prop_ref()

struct IC4_PROPERTY * ic4_prop_ref ( struct IC4_PROPERTY * prop )

Increases the property's internal reference count by one.

Parameters

[in] prop A property

Returns: The pointer passed via prop

Remarks: If prop is NULL, the function returns NULL. An error value is not set.

See also: ic4_prop_unref

◆ ic4_prop_unref()

void ic4_prop_unref ( struct IC4_PROPERTY * prop )

Decreases the property's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] prop A property

Remarks: If prop is NULL, the function does nothing. An error value is not set.

See also: ic4_prop_ref