class P1::CameraSdk::PropertyTransaction

Overview

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

#include <P1CameraTypes.hpp>

class PropertyTransaction
{
public:
    // construction

    PropertyTransaction(
        Camera& camera,
        const uint32_t propertyId,
        const PropertyValue& value
        );

    // methods

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

    void AndWaitFor(
        const uint32_t propertyId,
        std::function<bool(const PropertySpecification&)> condition,
        bool isPrecondition = true,
        const uint32_t timeout = 1000
        );

    void AndWaitForAll(
        const std::vector<uint32_t>& ids,
        std::function<bool(const PropertySpecification&)> condition,
        bool isPrecondition = true,
        const uint32_t timeout = 1000
        );
};

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

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

The Camera class has a method to create these PropertyTransaction objects Camera::BeginSetProperty

Construction

PropertyTransaction(
    Camera& camera,
    const uint32_t propertyId,
    const PropertyValue& 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.

Parameters:

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

Methods

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.

Parameters:

propertyId	The Id that we wait for a change notification for
timeout	The maximum time we will wait (in MS). 0 is forever

void AndWaitFor(
    const uint32_t propertyId,
    std::function<bool(const PropertySpecification&)> 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 PropertySpecification against a callback function.

The callback function takes the PropertySpecification 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 PropertySpecification 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.)

Parameters:

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

void AndWaitForAll(
    const std::vector<uint32_t>& ids,
    std::function<bool(const PropertySpecification&)> 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 PropertySpecification against a callback function.

The callback function takes the PropertySpecification 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.)

Parameters:

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