Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvDeviceEventSink Class Reference

Observer interface for an observable PvDevice object. More...

Public Member Functions

 PvDeviceEventSink ()
 Constructor.
 
virtual ~PvDeviceEventSink ()
 Destructor.
 
virtual void OnLinkDisconnected (PvDevice *aDevice)
 Notification that the PvDevice unexpectedly lost contact with the device. More...
 
virtual void OnLinkReconnected (PvDevice *aDevice)
 Deprecated, no longer used. More...
 
virtual void OnEvent (PvDevice *aDevice, uint16_t aEventID, uint16_t aChannel, uint64_t aBlockID, uint64_t aTimestamp, const void *aData, uint32_t aDataLength)
 Messaging channel raw event notification. More...
 
virtual void OnEventGenICam (PvDevice *aDevice, uint16_t aEventID, uint16_t aChannel, uint64_t aBlockID, uint64_t aTimestamp, PvGenParameterList *aData)
 Messaging channel GenICam event notification. More...
 
virtual void OnCmdLinkRead (const void *aBuffer, int64_t aAddress, int64_t aLength)
 Callback invoked after a port read. More...
 
virtual void OnCmdLinkWrite (const void *aBuffer, int64_t aAddress, int64_t aLength)
 Callback invoked after a port write. More...
 

Detailed Description

Observer interface for an observable PvDevice object.

PvDeviceEventSink defines a set of callback methods from a PvDevice object to any object implementing this interface.

GigE Vision Recovery

A PvDeviceGEV object continually sends a heartbeat message every HeartbeatInterval milliseconds to the connected GigE Vision device to maintain its control channel privilege and ensure that the two entities are aware of each other's continued existence.

If the GigE Vision device fails to receive a heartbeat message after a given period of time (see the GevHeartbeatTimeout GigE Vision parameter and DefaultHeartbeatTimeout), it loses its control channel privilege so that another controller may connect to the device in the event of a connection loss.

Each heartbeat sent by the PvDeviceGEV object is acknowledged by the device. If the GigE Vision device fails to respond to the heartbeat (within AnswerTimeout milliseconds) after CommandRetryCount retries, it considers itself disconnected and notifies any registered PvDeviceEventSink objects using the OnLinkDisconnected callback.

Device recovery (or reconnection) must be performed at the application level. After a OnLinkDisconnected callback, the current session should be cleaned up (disconnecting or deleting your PvDevice controller, closing your PvStream, etc.) and you should start polling with FindDevice from PvSystem to see when the device is available again. When the device is available, reconnect and restore any previously known good application configuration.

For a complete working example of how to initiate recovery and continue streaming in the event of a connection loss, refer to the ConnectionRecovery sample.

USB3 Vision Recovery

A PvDeviceU3V object continually sends a heartbeat message every HeartbeatInterval milliseconds to the connected USB3 Vision device to ensure that the two entities are aware of each other's continued existence.

If a PvDeviceU3V fails to respond to the heartbeat (within AnswerTimeout milliseconds), it considers itself disconnected and notifies any registered PvDeviceEventSink objects using the OnLinkDisconnected callback.

USB3 Vision devices do not require the heartbeat. There is no concept of control channel or even a heartbeat being required in order to keep the control channel opened. The heartbeat is only used for the host to know that the device is still connected and responsive.

See GigE Vision section above for instructions on how to perform application level recovery after a disconnect event.

Messaging channel events

To receive raw events notifications:

  1. Create an instance of your MySink class.
  2. Connect to the GigE Vision device as you normally would. See PvDevice.
  3. Register your MySink class with the PvDevice object. Use PvDevice::RegisterEventSink.
  4. Control the GigE Vision device as you normally would. See PvDevice.
  5. Handle events when PvDevice calls your OnEvent overridden method.

Member Function Documentation

◆ OnCmdLinkRead()

void PvDeviceEventSink::OnCmdLinkRead ( const void *  aBuffer,
int64_t  aAddress,
int64_t  aLength 
)
virtual

Callback invoked after a port read.

Used to report read activity on the GenApi IPort implementation of the command link of the PvDevice.

The callback is invoked AFTER the read operation so the content of aBuffer contains the data that was read from the device.

This callback is only invoked on a successful read operation.

If aLength is 4 bytes, that data is represented as a 4 bytes value formatted as big endian. If data is more that 4 bytes, it is presented as a stream of bytes requiring proper interpretation.

Parameters
[in]aBufferPointer to the data read.
[in]aAddressAddress of the data read on the device.
[in]aLengthLength of the data, in bytes.

◆ OnCmdLinkWrite()

void PvDeviceEventSink::OnCmdLinkWrite ( const void *  aBuffer,
int64_t  aAddress,
int64_t  aLength 
)
virtual

Callback invoked after a port write.

Used to report write activity on the GenApi IPort implementation of the command link of the PvDevice.

The callback is invoked AFTER the write operation. The content of aBuffer represents the data that was written to the device.

This callback is only invoked on a successful read operation.

If aLength is 4 bytes, that data is represented as a 4 bytes value formatted as big endian. If data is more that 4 bytes, it is presented as a stream of bytes requiring proper interpretation.

Parameters
[in]aBufferPointer to the data that was written.
[in]aAddressAddress of the data written to the device.
[in]aLengthLength of the data, in bytes.

◆ OnEvent()

void PvDeviceEventSink::OnEvent ( PvDevice aDevice,
uint16_t  aEventID,
uint16_t  aChannel,
uint64_t  aBlockID,
uint64_t  aTimestamp,
const void *  aData,
uint32_t  aDataLength 
)
virtual

Messaging channel raw event notification.

This OnEvent handler lets users access the raw GigE Vision or USB3 Vision event before it is forwarded to the GenApi layer.

Note
This callback is an advanced feature that should only be used by developers who are aware of the event IDs that are being sent from their device. It is recommended to use OnEventGenICam whenever possible.

Depending on the nature of the event being received, there may be data returned that is pointed to by aData (otherwise aData is NULL). This additional data is received on the wire in the device's Endianess.

All other parameters are provided in the Endianess of the host.

Parameters
[in]aDevicePointer to the PvDevice object that triggered the callback.
[in]aEventIDEvent ID. Some standard event IDs are defined but usually device dependent.
[in]aChannelStreaming channel associated with the event, if any. 0xFFFF is used if the event is not associated to a streaming channel.
[in]aBlockIDStreaming block ID associated with the event, if any. Can be used to pair one or more than one event with a block received from a device. 0 is used if the event is not associated to a block.
[in]aTimestampTimestamp of the event on the time domain of the device. Time unit is defined by the device. 0 if timestamps are not supported by the device that generated the event.
[in]aDataPointer to Event Data, if applicable. NULL otherwise.
[in]aDataLengthData length, in bytes.

Reimplemented in PvDeviceAdapter.

◆ OnEventGenICam()

void PvDeviceEventSink::OnEventGenICam ( PvDevice aDevice,
uint16_t  aEventID,
uint16_t  aChannel,
uint64_t  aBlockID,
uint64_t  aTimestamp,
PvGenParameterList aData 
)
virtual

Messaging channel GenICam event notification.

This OnEvent handler lets users access the event as mapped through the GenApi interface of the device.

Unlike the other OnEvent that provides a pointer to the raw event data, the data is provided as a list of GenApi parameters that have been invalidated when the event has been attached to the GenApi node map of the device.

If events with no data or events with data not mapped in the GenApi interface of the device are received, this callback is still invoked by the parameter list containing is not provided, it is simply set to NULL.

Parameters
[in]aDevicePointer to the PvDevice object that triggered the callback.
[in]aEventIDEvent ID. Some standard event IDs are defined but usually device dependent.
[in]aChannelStreaming channel associated with the event, if any. 0xFFFF is used if the event is not associated to a streaming channel.
[in]aBlockIDStreaming block ID associated with the event, if any. Can be used to pair one or more than one event with a block received from a device. 0 is used if the event is not associated to a block.
[in]aTimestampTimestamp of the event on the time domain of the device. Time unit is defined by the device. 0 if timestamps are not supported by the device that generated the event.
[in]aDataList containing all parameters invalidated by this event. Can be NULL if the event carried no data or the data was does not invalidate any GenApi parameters of the device.

◆ OnLinkDisconnected()

void PvDeviceEventSink::OnLinkDisconnected ( PvDevice aDevice)
virtual

Notification that the PvDevice unexpectedly lost contact with the device.

Parameters
[in]aDevicePointer to the device object that invoked this callback.

◆ OnLinkReconnected()

void PvDeviceEventSink::OnLinkReconnected ( PvDevice aDevice)
virtual

Deprecated, no longer used.

PvDevice no longer attempts automatic reconnection. After receiving an OnLinkDisconnected notification, it is recommend to properly complete disconnection at the application level and then either attempting reconnection until it succeeds or trying find the device in a loop with PvSystem::FindDevice until it succeeds and then finally reconnecting PvDevice, re-opening PvStream, etc.

Parameters
[in]aDevicePointer to the device object that invoked this callback.

The documentation for this class was generated from the following files:

Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com