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_PROPERTYic4_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]propThe property that has changed
[in]user_ptrThe 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_ptrThe 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

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

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_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

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]propA property
[in]handlerThe property notification handler to be called if prop changes
[in]user_ptrUser data to be passed to the notification handler
[in]deleterThe 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]propA property with a registered notification handler
[in]handlerThe property notification handler to be removed
[in]user_ptrThe 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]propA 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]propA 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]propA 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]propA property that is a selector
[out]ppSelectedA 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]propA 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]propA 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]propA 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]propA 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]propA 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]propA 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]propA 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]propA 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]propA 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]propA property
Remarks
If prop is NULL, the function does nothing. An error value is not set.
See also
ic4_prop_ref