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
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_tupleGetMessageTupleGetMessageTupleget_message_tuple retrieves a tuple associated with the KeyKeyKeykeykey
from the message denoted by the MessageHandleMessageHandleMessageHandlemessageHandlemessage_handle.
The tuple has to be previously stored to the message using
set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleset_message_tuple.
The operator returns the data in the parameter TupleDataTupleDataTupleDatatupleDatatuple_data.
The data including strings is copied by the operation, the message can thus
be immediately reused.
If the given KeyKeyKeykeykey is not present in the message or if the data
associated with the key is not a tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleget_message_tuple fails.
Presence of keys and information about the data associated with the key
can be verified using get_message_paramget_message_paramGetMessageParamGetMessageParamget_message_param.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameters
MessageHandleMessageHandleMessageHandlemessageHandlemessage_handle (input_control) message → HMessage, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Message handle.
Number of elements:
MessageHandle == 1
Restriction:
MessageHandle != 0
KeyKeyKeykeykey (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
TupleDataTupleDataTupleDatatupleDatatuple_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_tupleGetMessageTupleGetMessageTupleget_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_messageDequeueMessageDequeueMessagedequeue_message
Alternatives
get_message_objget_message_objGetMessageObjGetMessageObjget_message_obj
See also
create_messagecreate_messageCreateMessageCreateMessagecreate_message,
clear_messageclear_messageClearMessageClearMessageclear_message,
set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleset_message_tuple,
set_message_objset_message_objSetMessageObjSetMessageObjset_message_obj,
get_message_objget_message_objGetMessageObjGetMessageObjget_message_obj,
set_message_paramset_message_paramSetMessageParamSetMessageParamset_message_param,
get_message_paramget_message_paramGetMessageParamGetMessageParamget_message_param,
enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageenqueue_message,
dequeue_messagedequeue_messageDequeueMessageDequeueMessagedequeue_message
Module
Foundation