class P1::CameraSdk::Listener

Overview

Class that allows you to receive notifications for events. More…

#include <P1CameraListener.hpp>

class Listener
{
public:
    // construction

    Listener();
    Listener(const Camera& camera, EventType const& event);

    Listener(
        Camera const& camera,
        uint32_t const propertyId,
        bool isSpecificationChange = false
        );

    // methods

    EXPORT_API void EnableNotification(
        Camera const& camera,
        uint32_t const propertyId,
        bool isSpecificationChange = false
        );

    EXPORT_API void EnableNotification(
        Camera const& camera,
        EventType const& eventType
        );

    EXPORT_API void EnableNotification(SdkEventType const& eventType);

    EXPORT_API void DisableNotification(
        Camera const& camera,
        uint32_t const propertyId,
        bool isSpecificationChange = false
        );

    EXPORT_API void DisableNotification(
        Camera const& camera,
        EventType const& eventType
        );

    EXPORT_API void DisableNotification(SdkEventType const& eventType);
    EXPORT_API void EnableCatchAllNotifications();
    EXPORT_API void DisableCatchAllNotifications();
    EXPORT_API std::shared_ptr<INotificationEvent const> WaitForNotification(uint32_t timeoutMs = 0);
    EXPORT_API void WakeUpWaitingThread();
};

Detailed Documentation

Class that allows you to receive notifications for events.

The Listener is notification subscription and receive context. You enable notifications on a Listener object, and wait for incoming notifications on the same Listener.

You can create multiple listener objects, and enable different sets of notifications on them. Each listener will receive only notifications explicitly enable on each one of them.

One exception is if you enable “catch all” notifications on the listener. Then all notification generated by the CameraSDK, will be sent to the listener, even without a single call to EnableNotification(…).

When disable the “catch all” state on the listener, it returns to the normal operating state, delivering only enabled notifications.

Version 2.0

Construction

Listener()

Create an empty Listener object, with no enabled notifications

Listener(const Camera& camera, EventType const& event)

Create a Listener object, with specified notifications enabled for the passed camera.

Listener(
    Camera const& camera,
    uint32_t const propertyId,
    bool isSpecificationChange = false
    )

Create a Listener object, with specified property enabled for the passed camera.

Parameters:

camera	The camera who’s property we wish to receive notifications for
propertyId	The Id of the property we wish to receive notification for
isSpecificationChange	Set to `true` if you want specification state change notifications instead, `false` is value changes only

Methods

EXPORT_API void EnableNotification(
    Camera const& camera,
    uint32_t const propertyId,
    bool isSpecificationChange = false
    )

Enables receiving a specific property notification.

All properties belongs to a Camera. Therefore you must provide the camera from which you would like to receive notifications.

Further, there are two kind of property changes that can be enabled: value change and specification changes. Value changes are changes to a property’s current value. Specification changes are changes to the PropertySpecification object, and may changes such as read-only, range and value list state.

The default options is to enable value change notifications.

Parameters:

camera	The camera who’s property we wish to receive notifications for
propertyId	The Id of the property we wish to receive notification for
isSpecificationChange	Set to `true` if you want specification state change notifications instead, `false` is value changes only

EXPORT_API void EnableNotification(
    Camera const& camera,
    EventType const& eventType
    )

Enables receiving notifications for Camera events.

Parameters:

camera	The camera to enable the camera event notification on
type	The event type of the event to receive notifications for

EXPORT_API void EnableNotification(SdkEventType const& eventType)

Enables receiving notifications for SDK related events.

Parameters:

type	The SDK event type of the event to receive notifications for

EXPORT_API void DisableNotification(
    Camera const& camera,
    uint32_t const propertyId,
    bool isSpecificationChange = false
    )

Disable receiving property change notifications.

This causes the listener to stop receiving new notification for the specific property change event.

Parameters:

camera	The camera who’s property to stop receiving notifications for
propertyId	The Id of the property to stop receiving notification for
isSpecificationChange	Set to `true` to disable specification change notifications, `false` for value changes

EXPORT_API void DisableNotification(
    Camera const& camera,
    EventType const& eventType
    )

Disable receiving camera event notifications.

EXPORT_API void DisableNotification(SdkEventType const& eventType)

Disable receiving SDK event notifications.

EXPORT_API void EnableCatchAllNotifications()

Enable “catch all” state on this listener.

In “catch all” state, every notification generated by the SDK is delivered to this listener. (Across all opened cameras!)

This also has the effect of enabling notifications for properties that are not currently visible on the cameras. (Due to the cameras state.)

EXPORT_API void DisableCatchAllNotifications()

Disable “catch all” state on the listener.

This deactivates the delivery of all types of notifications to this listener. The listener state is returned to normal, where only enabled notification will be delivered. (The ones enabled calling EnableNotification)

Any explicitly enabled notifications will be preserved, and are thus not affected by disabling “catch all” state.

EXPORT_API std::shared_ptr<INotificationEvent const> WaitForNotification(uint32_t timeoutMs = 0)

Block until the next notification is received.

Parameters:

timeoutMs

Time in milliseconds to wait for next notification, before giving up. Zero (0) means wait forever.

Returns:

the notification that is received, if any (nullptr on timeout).

EXPORT_API void WakeUpWaitingThread()

Wakes up any thread that may be blocked in the WaitForNotification call.

Threads that are ‘waiting forever’ are also woken!