create_message — Create a new empty message.
create_message( : : : MessageHandle)
create_message creates a new empty message. The output parameter MessageHandle is a handle to the newly created message and is used to identify the message in any subsequent operator call using the message.
The message serves as a dictionary-like container allowing to store an arbitrary number of values associated with unique keys (strings). Each key can refer either to a control parameter tuple or to an iconic object. These data are stored to the message using set_message_tuple or set_message_obj, respectively, from where they can be retrieved again using get_message_tuple or get_message_obj.
The data stored in the message are always deep copies of the original data, being it control parameters or objects. The original data can thus be reused immediately after the set_message_tuple or set_message_obj calls without affecting the message. Notable exceptions are handles which are treated as regular integer values by HALCON, therefore storing any handle in the message will copy the handle value, but not the resource behind the handle.
Finally, the messages can be passed between the threads of an application using asynchronous message queues. The data can be appended to the queue by multiple producer threads using enqueue_message and retrieved from the queue by multiple receiver threads using dequeue_message. All these operations are internally properly synchronized. Therefore, the queue can be safely accessed by all producers and consumers without any explicit locking. Queuing a message creates a deep copy of all its data, therefore the message can be reused immediately after queuing.
When the message is no more needed, all associated resources, in particular the tuple or object data stored in the message, should be released using clear_message.
Handle of the newly created message.
Number of elements: MessageHandle == 1
Assertion: MessageHandle != 0
MessageHandles :=  for idx := 0 to 4 by 1 create_message (MessageHandle) MessageHandles[idx]:= MessageHandle endfor * ... clear_message (MessageHandles)
Returns 2 (H_MSG_TRUE) unless a resource allocation error occurs.
clear_message, set_message_tuple, get_message_tuple, set_message_obj, get_message_obj, set_message_param, get_message_param, enqueue_message, dequeue_message