set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj (Operator)

Name

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

Signature

set_message_obj(ObjectData : : MessageHandle, Key : )

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

ObjectDataObjectDataObjectDataObjectDataObjectDataobjectData is copied by the operation (copying the object data in HALCON's object database, see copy_objcopy_objCopyObjcopy_objCopyObjCopyObj), 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 (KeyKeyKeyKeyKeykey), the old data is destroyed by set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj and replaced by ObjectDataObjectDataObjectDataObjectDataObjectDataobjectData.

The KeyKeyKeyKeyKeykey has to be a non-empty string consisting solely of lowercase or uppercase ASCII letters, digits and underscores, while only a letter can be at the first position of the key. The key string is treated case sensitive.

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

Parallelization

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:

MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle

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

Parameters

ObjectDataObjectDataObjectDataObjectDataObjectDataobjectData (input_object) object(-array) → object

Object to be associated with the key.

MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (input_control, state is modified) message → (integer)

Message handle.

Number of elements: MessageHandle == 1

Restriction: MessageHandle != 0

KeyKeyKeyKeyKeykey (input_control) string → (string)

Key string.

Number of elements: Key == 1

Restriction: length(Key) > 0

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_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters (handle or key) or resource allocation error.