Listener Class

Definition

Namespace: P1.CameraSdk

An event listening context that receives events from Cameras or the SDK itself. More…

public class Listener :  IDisposable

Remarks

An event listening context that receives events from Cameras or the SDK itself.

Instances of this class acts as an event central, where notifications (events) are arriving from cameras and SDK. You should use a dedicated thread or task to handle all these incoming notifications.

Notifications

Before a listener will receive any notifications, you must Enable at least one notification. A notification can be one of three types: a property change, a camera action or an SDK event.

When a notification is enabled, events for this notification will begin arriving to the Listener object. At any time you can enable more notifications or disable them.

Handling incoming events

We are using a very simple scheme to handle events. Our aim is to be as generic and cross platform (or framework) as possible. You should handle incoming notifications in a separate thread, since our API methods are blocking.

To receive incoming events, a separate thread or task should call WaitForNotification(uint) from within an event processing loop. This call will block until an notification arrives, and the event should be handled. Then the thread should loop, to call WaitForNotification again.

Disposing and graceful termination

Because the event handling thread spend its time in a blocked call, you must take care of it when terminating your app. You can release all blocked threads blocked inside WaitForNotification(uint) by issueing a call to the WakeUpWaitingThread method, from any other thread.

Likewise, it is important to disable all notifications from any Camera that you are about to dispose.

Mapping to other events schemes

As previously stated, the event handling scheme is meant to be cross platform - not C#’ish in particular. Therefore we recommend that you integrate it with the native event system of your platform or framework.

Say you are working with WPF, you could integrate our notifications with System.ComponentModel.INotifyPropertyChanged scheme used by WPF. Other schemes could utlize the System.EventHandler delegate.

Sommon for all implementations, is that the event handling thread should only dispatch notification, not act upon them. All business logic called as a result of a incoming notification, must be delegated to other threads or tasks. This is important because it keeps the event handling thread responsive.

This example shows how to create a Listener and listen for 2 notifications. A dedicated thread is handling the incoming events, and gets signalled when the user presses the Enter key.

var eventCentral = new Listener();
var eventThread = new Thread(() => {
    while(true) {
        var notification = eventCentral.WaitForNotification();
        if (notification == null)
        {
            Console.WriteLine("Timeout or signalled wake-up!");
            break;
        }
        if (notification.mSdkEventId == SdkEventId.CameraAdded)
        {
            Console.WriteLine("Camera Added");
        }
        else if (notification.mSdkEventId == SdkEventId.CameraRemoved)
        {
            Console.WriteLine("Camera Removed");
        }
        else
        {
            Console.WriteLine("Got unknown: {0}", notification);
            break;
        }
    }
});

eventCentral.EnableNotification(SdkEventId.CameraAdded)
eventCentral.EnableNotification(SdkEventId.CameraRemoved)

Console.ReadLine("Press Enter to stop...");
eventCentral.WakeUpWaitingThreads();
eventThread.join();

As the example shows, you can begin listening for events, after you have started your event handler thread loop. Other threads can enable and disable notifications dynamically, meaning while the event handler thread is running.

Constructors

Listener()	Create an empty Listener object, with no enabled notifications
Listener(Camera camera, EventType eventType)	Create a Listener object, with specified notifications enabled for the passed camera.
Listener(Camera camera, UInt32 propertyId, bool isSpecificationChange=false)	Create a Listener object, with specified property enabled for the passed camera.

Properties

Id	Internal Id used by the underlying SDK event system

Methods

EnableNotification(Camera camera, UInt32 propertyId, bool isSpecificationChange=false)	Begin receiving property notifications from a specific camera
EnableNotification(Camera camera, EventType eventType)	Begin receiving camera action notifications from a specific camera
EnableNotification(SdkEventType sdkEventType)	Begin receiving SDK notifications, that is not related to a specific camera
EnableCatchAllNotifications()	Enable “catch all” state on this listener
DisableNotification(Camera camera, UInt32 propertyId, bool isSpecificationChange=false)	Stop receiving property changed notifications from a specific camera
DisableNotification(Camera camera, EventType cameraEventId)	Stop receiving camera action notifications from a specific camera
DisableNotification(SdkEventType sdkEvent)	Stop receiving SDK notifications
DisableCatchAllNotification()	Disable “catch all” state on the listener
WakeUpWaitingThread()	Wake up all threads blocked inside the `WaitForNotification` method
WaitForNotification(uint timeoutMs=0)	Block the thread and wait for the next notification to arrive
Dispose()	Invalidate this listener object, waking up all blocked threads and disabling all notifications.