set_message_objT_set_message_objSetMessageObjSetMessageObj (Operator)

Name

set_message_objT_set_message_objSetMessageObjSetMessageObj — Add a key/object pair to the message.

Signature

set_message_obj(ObjectData : : MessageHandle, Key : )

Description

set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj stores an object associated with a key in the message, which behaves as a dictionary-like data container. The message is denoted by the MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle parameter.

ObjectDataObjectDataObjectDataObjectDataobjectData is copied by the operation (copying the object data in HALCON's object database, see copy_objcopy_objCopyObjCopyObjCopyObj), and can thus be immediately reused. Both an empty object or an object tuple are considered as a valid value that can be associated with the key. If any data (tuple or object) was already associated with given key (KeyKeyKeyKeykey), the old data is destroyed by set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj and replaced by ObjectDataObjectDataObjectDataObjectDataobjectData.

The KeyKeyKeyKeykey has to be a string or an integer. String keys are treated case sensitive.

The object data for the given key can be retrieved again from the message using get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObj.

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

This operator modifies the state of the following input parameter:

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle

The value of this parameter may not be shared across multiple threads without external synchronization.

Parameters

ObjectDataObjectDataObjectDataObjectDataobjectData (input_object) object(-array) → object

Object to be associated with the key.

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (input_control, state is modified) message → (handle)

Message handle.

Number of elements: MessageHandle == 1

Restriction: MessageHandle != 0

KeyKeyKeyKeykey (input_control) string → (string / integer)

Key string or integer.

Number of elements: Key == 1

Example (HDevelop)

create_message (Message)
read_image( Image, 'filename')
set_message_obj (Image, Message, 'my_image')

Result

If the operation succeeds, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters (handle or key) or resource allocation error.