set_message_tupleT_set_message_tupleSetMessageTupleSetMessageTupleset_message_tuple (Operator)

Name

set_message_tupleT_set_message_tupleSetMessageTupleSetMessageTupleset_message_tuple — Add a key/tuple pair to the message.

Signature

set_message_tuple( : : MessageHandle, Key, TupleData : )

Herror T_set_message_tuple(const Htuple MessageHandle, const Htuple Key, const Htuple TupleData)

void SetMessageTuple(const HTuple& MessageHandle, const HTuple& Key, const HTuple& TupleData)

void HMessage::SetMessageTuple(const HTuple& Key, const HTuple& TupleData) const

void HMessage::SetMessageTuple(const HString& Key, const HTuple& TupleData) const

void HMessage::SetMessageTuple(const char* Key, const HTuple& TupleData) const

void HMessage::SetMessageTuple(const wchar_t* Key, const HTuple& TupleData) const   (Windows only)

static void HOperatorSet.SetMessageTuple(HTuple messageHandle, HTuple key, HTuple tupleData)

void HMessage.SetMessageTuple(HTuple key, HTuple tupleData)

void HMessage.SetMessageTuple(string key, HTuple tupleData)

def set_message_tuple(message_handle: HHandle, key: Union[str, int], tuple_data: Sequence[HTupleElementType]) -> None

Description

set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple stores a tuple associated with a key in the message, which behaves as a dictionary-like data container. The message is denoted by the MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle parameter.

TupleDataTupleDataTupleDataTupleDatatupleDatatuple_data including strings is copied by the operation, and can thus be immediately reused. An empty tuple is 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_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple and replaced by TupleDataTupleDataTupleDataTupleDatatupleDatatuple_data.

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

The tuple data for the given key can be retrieved again from the message using get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple.

Attention

Note that if the tuple contains any handles (which are treated as simple integers) only the handle values are copied by the operation, not the resources behind those handles.

Execution Information

This operator modifies the state of the following input parameter:

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle (input_control, state is modified)  message HMessage, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Message handle.

Number of elements: MessageHandle == 1

Restriction: MessageHandle != 0

KeyKeyKeyKeykeykey (input_control)  string HTupleUnion[str, int]HTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)

Key string or integer.

Number of elements: Key == 1

TupleDataTupleDataTupleDataTupleDatatupleDatatuple_data (input_control)  tuple-array HTupleSequence[HTupleElementType]HTupleHtuple (string / integer / real / handle) (string / int / long / double / HHandle) (HString / Hlong / double / HHandle) (char* / Hlong / double / handle)

Tuple value to be associated with the key.

Example (HDevelop)

create_message (Message)
set_message_tuple (Message, 'simple_integer', 27)
set_message_tuple (Message, 'simple_string', 'Hello world')
set_message_tuple (Message, 'mixed_tuple', ['The answer', 42])

Result

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

Possible Predecessors

create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message

Possible Successors

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj

Alternatives

set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj

See also

create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageClearMessageclear_message, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj, set_message_paramset_message_paramSetMessageParamSetMessageParamSetMessageParamset_message_param, get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message

Module

Foundation