Notifications#
Events happening in the camera can generate notifications that are received on the Host computer. These can be categorized in various ways, each indicating what payload data you can expect to receive with the notification.
Note
The notification API has changed from CameraSDK release version 2.0 to 3.0! If you previously worked with the notifications APIs in version 2.0, you will find that the API has completely changed in version 3.0. And that these are breaking changes!
All notifications have to be enabled for the events to generate notifications. These notifications can be enabled or disabled at any time.
To listen for notifications, create an instance of the Listener class:
P1::CameraSdk::Listener listener;
Listener listener = new Listener();
The Listener class acts as a notification central, where notifications from enabled events are received. You receive the incoming notifications by calling the blocking method: WaitForNotification on the Listener object. Since it is blocking, it should be called from a separate thread (see Begin Listening for Notifications).
A thread listening for notifications should be offloaded by using other threads to handle “reactions” to the notifications (see thread-model-label). If no thread is blocked inside WaitForNotification, notifications are queued in a first-in, first-out (FIFO) manner. The next call to WaitForNotification will return the next waiting notification, in order. This way, notifications are not lost.
Multiple notifications can be enabled per Listener instance. Furthermore, multiple Listener instances can be created as needed. Each instance of Listener acts independently of other Listener instances.
You can create multiple Listener objects that are set up to receive the notifications originating from the same events. In this case, each listener will actually receive the same notification object. That is why notification objects are delivered inside a std::shared_ptr object in C++.
Event Categories#
All notification types belong to a category. These denote the area the notification belongs to, and define what payload data is included in the notification object.
The following section provides a more detailed description of the categories.
SDK Events#
The SdkEvent category describes a change at the CameraSDK-level. For instance, if the CameraSDK discovers a USB-connected camera, a notification of the type “SdkEvent” is generated.
An example of listening for the event of a camera being found (CameraFound) is shown below:
listener.EnableNotification(P1::CameraSdk::SdkEventType::SdkCameraFound);
listener.EnableNotification(SdkEventId.CameraFound);
SDK Events will tell you when USB cameras are discovered and when they disappear. The CameraFound notification and its opposite CameraRemoved, inform you about the visible USB cameras. It does not matter whether you are connected (camera is opened) or not.
Caution
TCP/IP cameras are not discovered. You will not receive any found or removed notifications from TCP/IP cameras.
Camera Events#
The CameraEvent category of notifications reflects events in a connected (and opened) camera. For example, if the camera delivers an image to the SDK host. This can be seen in the example below:
listener.EnableNotification(camera, P1::CameraSdk::EventType::CameraImageReady);
listener.EnableNotification(camera, CameraEventId.ImageReady);
The Camera event category is further divided into 4 sub-categories: image receiving, connection, LiveView & property lifetime. The next few sections will examine these sub-categories in more detail.
Image Receiving#
These are camera events that provide progress reporting on the image transfer between the camera and the host. When the camera starts transferring an image, the ImageTransferBegin event is received. At rate-limited intervals, the SDK will provide the TransferProgress event until the entire image is present in SDK memory. Then ImageReady is received, and the image is included within that notification object.
Connection#
The Disconnected camera event indicates that the connection (USB / TCP) has been lost. This is either by intention or as a result of a link error. You will receive the Disconnect event after calling Close on the camera. Similarly, you will receive the same event if the USB or network cable is unplugged suddenly. The Disconnect event itself cannot tell you which scenario it originates from.
Caution
TCP sockets on specific platforms are very forgiving and will try to keep the TCP connection open for several minutes.
If you are on a poor-quality Wifi, this is probably a desired behavior. On the other hand, if you are on cabled and switched Ethernet, then even an unplugged cable is not enough to interrupt the established TCP connection.
LiveView#
The LiveView-related camera events will indicate when LiveView is started or stopped. Also, the NewLiveViewImage event type provides you with the new LiveView image inside the notification object.
If you are working with an IQ4 digital back, starting LiveView on the camera’s display will not trigger any LiveView notifications in the SDK. LiveView notifications received in the SDK are when the SDK itself uses LiveView.
Property Lifetime#
These are camera events that advertise about camera properties that appear or disappear. The camera can change mode, which may trigger new properties to become available. Likewise, changing a mode on the camera may cause some properties to disappear.
Property Events#
A PropertyEvent-type notification is triggered upon the changing of a value in a property, such as the “aperture” being set to “5.6”.
To receive notifications about property events, notifications have to be enabled for the desired property (e.g., “aperture” or “ISO”).
When enabling notifications for a property, a notification arrives when the property changes its value.
An example of how to listen for a change in the “aperture”-property can be seen below:
listener.EnableNotification(camera, 1003); // Aperture
listener.EnableNotification(camera, 1003); // Aperture
Note
An attempt to set the value to its current value (e.g., “5.6” –> “5.6”) will not generate a notification.
Specification Change Events#
By default, a property event denotes a change in the property’s value. However, the property’s specification (PropertySpec) may also change. These changes could be the read-only state or a change in the list of valid values (the value map).
Just as you can listen for value changes, you can likewise listen for specification changes - that does not change the property’s value.
Arriving specification change notifications are of the SpecificationChange type, whereas property value change notifications are of type Property.
To enable notifications for specification changes, you use the same EnableNotification method, but provide a 3rd argument:
listener.EnableNotification(camera, 1003, true); // 1003 is Aperture
listener.EnableNotification(camera, 1003, isSpecificationChange: true); // 1003 is Aperture
This third and optional argument defaults to false. If you explicitly set it to true you will receive only specification state changes for the given property id and camera.
You can enable both property value and specification change notifications by making two calls to the method—one for each type. They can exist independently of each other.
Similarly, you disable specification changes by calling DisableNotification and providing a 3rd argument set to true:
listener.DisableNotification(camera, 1003, true); // 1003 is Aperture
listener.DisableNotification(camera, 1003, isSpecificationChange: true); // 1003 is Aperture
Begin Listening for Notifications#
When notifications have been enabled for the desired events, the listening for notifications can begin. A thread must continuously listen for events, regardless of the event type. This thread executes the WaitForNotification method, as can be seen below:
void listenRoutine(P1::CameraSdk::Listener listener)
{
std::shared_ptr<P1::CameraSdk::INotificationEvent const> arrivedNotification;
while (true)
{
arrivedNotification = listener.WaitForNotification();
if ( ! arrivedNotification)
{
std::cout << "Wait timeout!\n";
}
else if (arrivedNotification->Type() == P1::CameraSdk::SdkEventType::SdkWakeUp)
{
std::cout << "SDK signalled wake-up" << std::endl;
}
else
{
std::cout << "Notification received:" << arrivedNotification->ToString() << std::endl;
}
}
}
var listenThread = new Thread(() => {
while (true)
{
NotificationEvent? notification = listener.WaitForNotification();
if (notification.HasValue == false)
{
Console.WriteLine("Signalled wake-up!");
break;
}
if (notification.Value.SdkEventId == SdkEventId.CameraFound)
{
Console.WriteLine("Camera Found");
break;
}
// Handle other notification types here...
else if (notification.Value.PropertyId == apertureId)
{
Console.WriteLine("Aperture changed");
break;
}
else
{
Console.WriteLine("Got unexpected: {0}", notification);
break;
}
}
});
listenThread.Start();
Output: (if the notification was not otherwise handled):
Notification received: Notification CameraImageReady, CamId: 1,
Stop Listening for Notifications#
Upon terminating the application, the thread listening for notifications should also terminate. To accomplish this, the CameraSDK has a function to release the thread listening for notifications in the specific Listener, as follows:
// Force the pending thread in WaitForNotification() to be released
listener.WakeUpWaitingThread();
// Wait here until listen thread has terminated gracefully
listenThread.join();
// Force the pending thread in WaitForNotification() to be released
listener.WakeUpWaitingThread();
// Wait here until listen thread has terminated gracefully
listenThread.Join();
Notification Payloads#
Each notification type can deliver optional payloads or context data. The NotificationEvent object defines members that are populated only for specific notification and event types. These members provide contextual information about the notification.
The table below lists the available payload members of NotificationEvent and the conditions that must be met for them to be populated with meaningful values:
Member Field |
Description |
Condition |
|---|---|---|
ImageId |
The image id of the image this event relates to |
All Image Receiving sub-category notifications |
CameraId |
The id of the camera that the notification relates to |
All Camera category notifications |
PropertyId |
The Id of the property that is changed |
All |
BasicImageInfo |
The BasicImageInfo object included in the notification |
Present only for notifications of
|
Preview |
The Preview image object included in the notification |
Present only for notifications of
|
Tile |
The Tile image object included in the notification |
Present only for notifications of
|
LiveView |
The LiveView image object included in the notification |
Present only for notifications of
|
FullImage |
The FullImage IIQ file included in the notification |
Present only for notifications of
|
StoredImageHandle |
The handle to the in camera image |
Present for |
CameraInfo |
A small struct describing the cameras connection type, IP, serial, etc. |
|
TransferProgressPercent |
A progress status for image transfers, in percent. |
CameraEvent category events,
where the sub-category is
|
ImageFilename |
The filename of the image that was transferred |
Any of the Transfer sub-category notifications |
Catch All Listeners#
The Listener class has a special catch-all state that enables receiving every single notification posted by the SDK, without the need to call EnableNotification for each notification first.
Notifications are received for all notification types, for every event, across all open cameras. Additionally, notifications will be enabled for properties that are not yet visible (due to the camera’s state).
If you enable the catch all state on a Listener before you open the first camera, you will receive the (CameraEvent type) notification CameraEventPropertyAdded, when you open any cameras.
To enable catch-all on a Listener instance:
listener.EnableCatchAllNotifications();
listener.EnableCatchAllNotifications();
Disable Catch All State#
The catch-all state can be disabled at any time by calling:
listener.DisableCatchAllNotifications();
listener.DisableCatchAllNotifications();
This effectively deactivates the delivery of all notification types to the Listener instance. The instance’s state is returned to normal, where only enabled notifications will be delivered. (The ones enabled by calling EnableNotification.)
If Listener already has any explicitly enabled notifications, these will be preserved. Thus, these are not affected by disabling the catch-all state.
Warning
Be aware that disabling the catch-all state does not clear the listeners’ queue of incoming notifications. Calls to WaitForNotification might return notifications queued up before the call to DisableCatchAllNotifications.