Topics
	Queue

	Message

	Message Data

Enumerations
enum	peak_message_type { PEAK_MESSAGE_TYPE_INVALID , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_CRITICAL_ERROR , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_ERROR , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EVENT_DROPPED , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EXPOSURE_START , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EXPOSURE_END , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_FRAME_START , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_FRAME_DROPPED , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_MISSED_TRIGGER_EXPOSURE , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_MISSED_TRIGGER_LINE , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_PTP_MASTER_SYNC_LOST , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_TEMPERATURE , PEAK_MESSAGE_TYPE_REMOTE_DEVICE_TEST , PEAK_MESSAGE_TYPE_DEVICE_FOUND , PEAK_MESSAGE_TYPE_DEVICE_LOST , PEAK_MESSAGE_TYPE_DEVICE_RECONNECTED , PEAK_MESSAGE_TYPE_DEVICE_DISCONNECTED , PEAK_MESSAGE_TYPE_AUTO_FOCUS_ONCE_FINISHED , PEAK_MESSAGE_TYPE_AUTO_FOCUS_NEW_DATA , PEAK_MESSAGE_TYPE_AUTO_WHITEBALANCE_ONCE_FINISHED , PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_GAIN_ONCE_FINISHED , PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_EXPOSURE_ONCE_FINISHED , PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_ONCE_FINISHED , PEAK_MESSAGE_TYPE_FIRMWARE_UPDATE }
	The peak message types. More...

Detailed Description

The Message Queue is used to notify the user of changes by the api.

Workflow

The MessageQueue is used to handle the remote device events, callbacks from the device manager and internal events. It is possible to have more than one message queue and each message queue can handle different messages. It is also possible for a single queue to handle multiple cameras.

In short, the following steps are needed to create a message queue:

Create a new queue: peak_MessageQueue_Create
Enable the needed message types: peak_MessageQueue_EnableMessage or peak_MessageQueue_EnableMessageList (Supply PEAK_INVALID_HANDLE as hCam for system message types here)
Start the queue: peak_MessageQueue_Start

peak_message_queue_handle hMessageQueue;
if (peak_MessageQueue_Create(&hMessageQueue) != PEAK_STATUS_SUCCESS)
{
    // handle error
}
 
if (peak_MessageQueue_EnableMessage(hMessageQueue, hCam, PEAK_MESSAGE_TYPE_REMOTE_DEVICE_TEMPERATURE) != PEAK_STATUS_SUCCESS)
{
    // handle error
}
 
if (peak_MessageQueue_Start(hMessageQueue) != PEAK_STATUS_SUCCESS)
{
    // handle error
}

After this, the message queue needs to be pulled periodically by a call to peak_MessageQueue_WaitForMessage. The function call is blocking and only returns after the timeout expires, the queue is stopped by a call to peak_MessageQueue_Stop or a new message is received. Please also note, that the function may return with PEAK_STATUS_WARNING_OVERFLOW in case the queue is overflowing and can't accept new messages. After processing the message it needs to be released by a call to peak_Message_Release.

peak_message_handle hMessage;
peak_status = peak_MessageQueue_WaitForMessage(hMessageQueue, PEAK_INFINITE, &hMessage);
if (PEAK_SUCCESS(status)) // also handles #PEAK_STATUS_WARNING_OVERFLOW, as it's only a warning
{
    // do something with message, e.g.
    peak_message_info message_info;
    if (peak_Message_GetInfo(hMessage, &message_info) == PEAK_STATUS_SUCCESS)
    {
        // work with message info e.g.
        printf("New Message: %d\n", message_info->type);
    }
 
    // don't forget to release the message!
    peak_Message_Release(hMessage);
}
else if (status == PEAK_STATUS_ABORTED)
{
    // handle abort
}
else
{
    // handle serious error
}

If the message has additional data (if peak_message_info::dataType is not PEAK_MESSAGE_DATA_TYPE_NO_DATA), the correct function for the type needs to be called. The correlation is as follows:

The following example shows the call to peak_Message_Data_RemoteDeviceTemperature_Get. Calls to the other functions are likewise:

peak_message_data_remote_device_temperature remoteDeviceTemperature;
if (peak_Message_Data_RemoteDeviceTemperature_Get(hMessage, &remoteDeviceTemperature) == PEAK_STATUS_SUCCCESS)
{
    double fahrenheit = remoteDeviceTemperature.temperature * 9.0 / 5.0 + 32.0;
 
    printf("DeviceTimestamp: %" PRIu64 ", Temperature: %.2f °C / %.2f °F",
        remoteDeviceTemperature.timestamp_ns, remoteDeviceTemperature.temperature, fahrenheit);
}

To stop the message queue and release peak_MessageQueue_WaitForMessage if PEAK_INFINITE was supplied, call peak_MessageQueue_Stop:

if (peak_MessageQueue_Stop(hMessageQueue) != PEAK_STATUS_SUCCCESS)
{
    // handle error
}

To destroy the message queue, call peak_MessageQueue_Destroy. After the call the handle is invalid and can no longer be used:

if (peak_MessageQueue_Destroy(hMessageQueue) != PEAK_STATUS_SUCCCESS)
{
    // handle error
}

Diagram

The following diagram shows the needed steps to create, configure, handle and destroy a message queue:

Enumeration Type Documentation

◆ peak_message_type

enum peak_message_type

The peak message types.

Enumeration of valid message types.

Enumerator
PEAK_MESSAGE_TYPE_INVALID	Invalid message type.
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_CRITICAL_ERROR	Remote device critical error message type. This will be generated when a critical error is detected. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_ERROR	Remote device error message type. This will be generated when an error is detected. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EVENT_DROPPED	Remote device event dropped message type. Will be generated when one or more events are lost. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EXPOSURE_START	Remote device exposure start message type. The camera started the exposure of a frame (or line in Linescan mode). Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_EXPOSURE_END	Remote device exposure end message type. The camera completed the exposure of a frame (or line in Linescan mode). Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_FRAME_START	Remote device frame start message type. The camera started the capture of a frame. Only available in Linescan mode. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_FRAME_DROPPED	Remote device frame dropped message type. Will be generated when one or more frames are lost. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_MISSED_TRIGGER_EXPOSURE	Remote device missed trigger exposure message type. The camera missed a trigger to start the exposure. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_MISSED_TRIGGER_LINE	Remote device missed trigger line message type. The camera missed a trigger to start the capture of a line. Only available in Linescan mode. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_PTP_MASTER_SYNC_LOST	Remote device missed ptp master sync lost message type. It will be generated when ptp master sync is lost. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_TEMPERATURE	Remote device temperature message type. It will be generated when the temperature deviates by more than 0.5 degrees from the previous value. Note Camera message
PEAK_MESSAGE_TYPE_REMOTE_DEVICE_TEST	Remote device test message type. It will be generated by calling the TestEventGenerate command node. (Note: use GFA here) Note Camera message
PEAK_MESSAGE_TYPE_DEVICE_FOUND	Camera manager device found message type. Will be generated when a device was found. Will only be signaled if peak_CameraList_Update is called e.g. periodically in a thread. Note System message
PEAK_MESSAGE_TYPE_DEVICE_LOST	Camera manager device lost message type. Will be generated when a device was lost. Will only be signaled if peak_CameraList_Update is called e.g. periodically in a thread. Note System message
PEAK_MESSAGE_TYPE_DEVICE_RECONNECTED	Camera manager device reconnected message type. Remarks System message
PEAK_MESSAGE_TYPE_DEVICE_DISCONNECTED	Camera manager device disconnected message type. Remarks System message
PEAK_MESSAGE_TYPE_AUTO_FOCUS_ONCE_FINISHED	Autofeature auto focus once finished message type. It will be generated when the host auto focus finished in PEAK_AUTO_FEATURE_MODE_ONCE mode. See Auto focus control for how to use it. It is only available for auto focus cameras. Note Autofeature message
PEAK_MESSAGE_TYPE_AUTO_FOCUS_NEW_DATA	Autofeature auto focus new data message type. It will be generated by host auto focus for each Focus value with its corresponding sharpness value. See Auto focus control for how to use it. It is only available for auto focus cameras. Note Autofeature message
PEAK_MESSAGE_TYPE_AUTO_WHITEBALANCE_ONCE_FINISHED	Autofeature auto whitebalance once finished message type. It will be generated when the host auto whitebalance finished in PEAK_AUTO_FEATURE_MODE_ONCE mode. See Auto white balance control for how to use it. Note Autofeature message
PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_GAIN_ONCE_FINISHED	Autofeature auto brightness gain once finished message type. It will be generated when the host auto brightness gain part finished in PEAK_AUTO_FEATURE_MODE_ONCE mode. See Auto brightness control for how to use it. Note Autofeature message
PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_EXPOSURE_ONCE_FINISHED	Autofeature auto brightness exposure once finished message type. It will be generated when the host auto brightness exposure part finished in PEAK_AUTO_FEATURE_MODE_ONCE mode. See Auto brightness control for how to use it. Note Autofeature message
PEAK_MESSAGE_TYPE_AUTO_BRIGHTNESS_ONCE_FINISHED	Autofeature auto brightness once finished message type. It will be generated when the host auto brightness finished in PEAK_AUTO_FEATURE_MODE_ONCE mode. See Auto brightness control for how to use it. Note Autofeature message
PEAK_MESSAGE_TYPE_FIRMWARE_UPDATE	Firmware update message type. It will be generated when a firmware update reports a status change. See Firmware Update for how to use it. Note Firmware update message

Topics

Enumerations

Detailed Description

Workflow

Diagram

Enumeration Type Documentation

◆ peak_message_type