.. index:: pair: class; P1::CameraSdk::PropertyTransaction
.. _doxid-class_p1_1_1_camera_sdk_1_1_property_transaction:

class P1::CameraSdk::PropertyTransaction
========================================

.. toctree::
	:hidden:

Overview
~~~~~~~~

A transaction that can set a property and wait for a change notification. :ref:`More...<details-class_p1_1_1_camera_sdk_1_1_property_transaction>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <P1CameraTypes.hpp>
	
	class PropertyTransaction
	{
	public:
		// construction
	
		:ref:`PropertyTransaction<doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1ad5ca7bc0dbd75d2ab53f76656466daf0>`(
			:ref:`Camera<doxid-class_p1_1_1_camera_sdk_1_1_camera>`& camera,
			const uint32_t propertyId,
			const :ref:`PropertyValue<doxid-struct_p1_1_1_camera_sdk_1_1_property_value>`& value
			);

		// methods
	
		void :ref:`AndWaitFor<doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a8dd08a30fd3304635211e72e4da80b38>`(const uint32_t propertyId, const uint32_t timeout = 1000);
	
		void :ref:`AndWaitFor<doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a8d8f9b696fb7eba34403761fec48bbd4>`(
			const uint32_t propertyId,
			std::function<bool(const :ref:`PropertySpecification<doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>`&)> condition,
			bool isPrecondition = true,
			const uint32_t timeout = 1000
			);
	
		void :ref:`AndWaitForAll<doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a0ddcc472db715ba92477ffe24f52b320>`(
			const std::vector<uint32_t>& ids,
			std::function<bool(const :ref:`PropertySpecification<doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>`&)> condition,
			bool isPrecondition = true,
			const uint32_t timeout = 1000
			);
	};
.. _details-class_p1_1_1_camera_sdk_1_1_property_transaction:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

A transaction that can set a property and wait for a change notification.

Since setting a property is asynchronous by nature, you can use this helper class to chain setting one property after a anothers *change notification* has arrived.

This is particularly useful when setting one property, puts another out of *read only* state. Then you *must* wait for the first property to be in effect, before you are allowed to modify the second.

This class is purely a helper class, meaning that it uses only the existing public API. It creates a :ref:`Listener <doxid-class_p1_1_1_camera_sdk_1_1_listener>`, and then wait for one or more property *change notifications*, before it completes the transaction.

In this example we use a transaction to set the *exposure program* and wait for it to be in effect, before we can set the ISO value:

.. ref-code-block:: cpp

	uint32_t exposureProgramId = 1000;
	uint32_t isoId = 120;
	:ref:`PropertyTransaction <doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1ad5ca7bc0dbd75d2ab53f76656466daf0>` expoProg(camera, exposureProgramId, :ref:`PropertyValue::CreateEnum <doxid-struct_p1_1_1_camera_sdk_1_1_property_value_1a1f33c2785fc828fcbd062908f99c7390>`(0));
	expoProg.AndWaitFor(exposureProgramId); // wait until property is in effect
	camera.SetProperty(isoId, PropertyValue(800)); // now, set the ISO value

The :ref:`Camera <doxid-class_p1_1_1_camera_sdk_1_1_camera>` class has a method to create these :ref:`PropertyTransaction <doxid-class_p1_1_1_camera_sdk_1_1_property_transaction>` objects :ref:`Camera::BeginSetProperty <doxid-class_p1_1_1_camera_sdk_1_1_camera_1afe867f5c11cc1a790876d6192073b1da>`

Construction
------------

.. index:: pair: function; PropertyTransaction
.. _doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1ad5ca7bc0dbd75d2ab53f76656466daf0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	PropertyTransaction(
		:ref:`Camera<doxid-class_p1_1_1_camera_sdk_1_1_camera>`& camera,
		const uint32_t propertyId,
		const :ref:`PropertyValue<doxid-struct_p1_1_1_camera_sdk_1_1_property_value>`& value
		)

Create a transaction that starts with the provided Property *Id* and value.

This constructs the transaction object, but actual setting the property on the camera, does not happen here. It happens when you call one of the multiple ``AndWaitFor`` methods.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- camera

		- The camera that the property should be applied to

	*
		- propertyId

		- The *Id* of the first property to set

	*
		- value

		- The value that the first property is set to



.. rubric:: See also:

:ref:`AndWaitFor(const uint32_t, const uint32_t) <doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a8dd08a30fd3304635211e72e4da80b38>`

Methods
-------

.. index:: pair: function; AndWaitFor
.. _doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a8dd08a30fd3304635211e72e4da80b38:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void AndWaitFor(const uint32_t propertyId, const uint32_t timeout = 1000)

Begins the transaction by applying the property provided in the constructor, and then wait for a *change notification* with the provided *Id*

First the property provided in the transactions constructor is applied. Then wait for the first property value *change notification* to arrive for the provided property *Id*.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- propertyId

		- The *Id* that we wait for a *change notification* for

	*
		- timeout

		- The maximum time we will wait (in MS). 0 is forever

.. index:: pair: function; AndWaitFor
.. _doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a8d8f9b696fb7eba34403761fec48bbd4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void AndWaitFor(
		const uint32_t propertyId,
		std::function<bool(const :ref:`PropertySpecification<doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>`&)> condition,
		bool isPrecondition = true,
		const uint32_t timeout = 1000
		)

Begins the transaction and wait for a *change notification*, for a property, who's specification fulfills a condition.

Applies the property supplied in the constructor and then wait for a value *change notification*. Then validate the :ref:`PropertySpecification <doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>` against a callback function.

The callback function takes the :ref:`PropertySpecification <doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>` that triggered the *change notification* and must return ``true`` or ``false``. If ``true`` the call returns. Otherwise, we keep waiting on *change notifications*.

You can choose to also validate the :ref:`PropertySpecification <doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>` against the callback, *before* we wait for the *change notification*. This allows you to handle situations, where a *change notification* never arrives, because you are not changing the property's value. (It already has the value, you are trying to set it to.)



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- propertyId

		- The *Id* that we wait for a *change notification* for

	*
		- condition

		- The callback function, that validate the arriving property changes

	*
		- isPrecondition

		- Defaults to ``true``, if you want to also validate, *before* you wait for changes

	*
		- timeout

		- An optional timeout in MS, before you give up waiting. 0 is forever

.. index:: pair: function; AndWaitForAll
.. _doxid-class_p1_1_1_camera_sdk_1_1_property_transaction_1a0ddcc472db715ba92477ffe24f52b320:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void AndWaitForAll(
		const std::vector<uint32_t>& ids,
		std::function<bool(const :ref:`PropertySpecification<doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>`&)> condition,
		bool isPrecondition = true,
		const uint32_t timeout = 1000
		)

Begins the transaction and wait for *change notifications*, for **all** provided property Ids, who's specification fulfills a condition.

Applies the property supplied in the constructor and then wait for a value *change notification* for **all** the provided property *Ids*. Then validate each :ref:`PropertySpecification <doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>` against a callback function.

The callback function takes the :ref:`PropertySpecification <doxid-struct_p1_1_1_camera_sdk_1_1_property_specification>` that triggered the *change notification* and must return ``true`` or ``false``. When the *condition* callback has returned ``true`` every provided property *id*, the call returns.

You can choose to also validate the PropertySpecifications against the callback, *before* you wait for the *change notifications*. This allows you to handle situations, where a *change notification* never arrives, because you are not changing the property's value. (It already has the value, you are trying to set it to.)



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- propertyIds

		- The *Ids* that we wait for *change notifications* for

	*
		- condition

		- The callback function, that validate the arriving property changes

	*
		- isPrecondition

		- Defaults to ``true``, if you want to also validate, *before* you wait for changes

	*
		- timeout

		- An optional timeout in MS, before you give up waiting. 0 is forever