Skip to content

set_message_paramSetMessageParamSetMessageParamset_message_paramT_set_message_param🔗

Short description🔗

set_message_paramSetMessageParamSetMessageParamset_message_paramT_set_message_param — Set message parameter or invoke commands on the message.

Signature🔗

set_message_param( message MessageHandle, string GenParamName, string Key, tuple GenParamValue )void SetMessageParam( const HTuple& MessageHandle, const HTuple& GenParamName, const HTuple& Key, const HTuple& GenParamValue )static void HOperatorSet.SetMessageParam( HTuple messageHandle, HTuple genParamName, HTuple key, HTuple genParamValue )def set_message_param( message_handle: HHandle, gen_param_name: str, key: MaybeSequence[Union[str, int]], gen_param_value: MaybeSequence[Union[int, float, str]] ) -> None

Herror T_set_message_param( const Htuple MessageHandle, const Htuple GenParamName, const Htuple Key, const Htuple GenParamValue )

void HMessage::SetMessageParam( const HString& GenParamName, const HTuple& Key, const HTuple& GenParamValue ) const

void HMessage::SetMessageParam( const HString& GenParamName, const HString& Key, const HTuple& GenParamValue ) const

void HMessage::SetMessageParam( const char* GenParamName, const char* Key, const HTuple& GenParamValue ) const

void HMessage::SetMessageParam( const wchar_t* GenParamName, const wchar_t* Key, const HTuple& GenParamValue ) const (Windows only)

void HMessage.SetMessageParam( string genParamName, HTuple key, HTuple genParamValue )

void HMessage.SetMessageParam( string genParamName, string key, HTuple genParamValue )

Description🔗

set_message_paramSetMessageParam sets message parameters or invokes action commands on the message.

For each call of set_message_paramSetMessageParam, only a single parameter can be set. However, there are two types of parameters/commands:

  • Parameters/commands applicable to the entire message. In this case no keys must be specified, i.e., the parameter Keykeykey must be an empty tuple.

  • Parameters/commands applicable to the individual keys. In this case a non-empty list of keys must be specified in parameter Keykeykey. The keys are processed in the same order as specified in the Keykeykey parameter.

Key-independent parameter names:

  • 'remove_all_keys'"remove_all_keys": Removes all the keys currently stored in the message and releases all the (control or iconic) data associated with those keys. The operation results in an empty message. Note that contents of GenParamValuegenParamValuegen_param_value is ignored for this parameter, while Keykeykey must be an empty tuple.

Key-specific parameter names:

  • 'remove_key'"remove_key": Removes the keys specified in the Keykeykey parameter and releases all the (tuple or object) data associated with those keys. If an error occurs while processing one or more keys (in particular if the key is invalid), the operator attempts to continue removing as many keys as possible before reporting the failure. Note that the contents of GenParamValuegenParamValuegen_param_value is ignored for this parameter.

Execution information🔗

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:

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

Parameters🔗

MessageHandlemessageHandlemessage_handle (input_control, state is modified) message → (handle)HTuple (HHandle)HMessage, HTuple (IntPtr)HHandleHtuple (handle)

Message handle.

Number of elements: MessageHandle == 1
Restriction: MessageHandle != 0

GenParamNamegenParamNamegen_param_name (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Names of the message parameters or action commands.

Number of elements: GenParamName == 1
Default: 'remove_key'"remove_key"
List of values: 'remove_all_keys', 'remove_key'"remove_all_keys", "remove_key"

Keykeykey (input_control) string(-array) → (string / integer)HTuple (HString / Hlong)HTuple (string / int / long)MaybeSequence[Union[str, int]]Htuple (char* / Hlong)

Message keys the parameter/command should be applied to.

GenParamValuegenParamValuegen_param_value (input_control) tuple(-array) → (string / integer / real)HTuple (HString / Hlong / double)HTuple (string / int / long / double)MaybeSequence[Union[int, float, str]]Htuple (char* / Hlong / double)

Values of the message parameters or action commands.

Example🔗

(HDevelop)

* Remove some keys
set_message_param (Message, 'remove_key', ['my_image', 'simple_string'], [])

Result🔗

If all the operator parameters, and their values, as well as specified keys are valid, set_message_paramSetMessageParam returns 2 (H_MSG_TRUE). Otherwise an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

dequeue_messageDequeueMessage, create_messageCreateMessage

Possible successors

enqueue_messageEnqueueMessage, clear_messageClearMessage

See also

create_messageCreateMessage, clear_messageClearMessage, set_message_tupleSetMessageTuple, get_message_tupleGetMessageTuple, set_message_objSetMessageObj, get_message_objGetMessageObj, get_message_paramGetMessageParam, enqueue_messageEnqueueMessage, dequeue_messageDequeueMessage

Module🔗

Foundation