get_message_tupleT_get_message_tupleGetMessageTupleGetMessageTupleget_message_tuple (Operator)

Name

get_message_tupleT_get_message_tupleGetMessageTupleGetMessageTupleget_message_tuple — Retrieve a tuple associated with the key from the message.

Signature

get_message_tuple( : : MessageHandle, Key : TupleData)

Herror T_get_message_tuple(const Htuple MessageHandle, const Htuple Key, Htuple* TupleData)

void GetMessageTuple(const HTuple& MessageHandle, const HTuple& Key, HTuple* TupleData)

HTuple HMessage::GetMessageTuple(const HTuple& Key) const

HTuple HMessage::GetMessageTuple(const HString& Key) const

HTuple HMessage::GetMessageTuple(const char* Key) const

HTuple HMessage::GetMessageTuple(const wchar_t* Key) const   (Windows only)

static void HOperatorSet.GetMessageTuple(HTuple messageHandle, HTuple key, out HTuple tupleData)

HTuple HMessage.GetMessageTuple(HTuple key)

HTuple HMessage.GetMessageTuple(string key)

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

def get_message_tuple_s(message_handle: HHandle, key: Union[str, int]) -> HTupleElementType

Description

get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple retrieves a tuple associated with the KeyKeyKeyKeykeykey from the message denoted by the MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle. The tuple has to be previously stored to the message using set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple.

The operator returns the data in the parameter TupleDataTupleDataTupleDataTupleDatatupleDatatuple_data. The data including strings is copied by the operation, the message can thus be immediately reused.

If the given KeyKeyKeyKeykeykey is not present in the message or if the data associated with the key is not a tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple fails. Presence of keys and information about the data associated with the key can be verified using get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param.

Execution Information

Parameters

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle (input_control)  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 (output_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 retrieved from the message.

Example (HDevelop)

* ...
get_message_param (Message,'key_exists',['simple_string','foo','my_image'],\
                   KeysPresence)
get_message_param (Message,'key_data_type',['simple_string','my_image'],\
                   KeysType)
get_message_tuple (Message,'simple_string',TupleString)

Result

If the operation succeeds, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters (handle or key), the required key not found in the message, or other than tuple data associated with given key.

Possible Predecessors

dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message

Alternatives

get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj

See also

create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageClearMessageclear_message, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_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