Javascript Message

Revision as of 15:48, 30 August 2024

Yate Message object

Constructor

• new Message(name)
• new Message(name,broadcast,obj)

Parameters:
name - Name of the message to create (mandatory)
broadcast - Optional boolean flag to create a broadcast message
obj - Optional object from which to copy properties as message parameters. Objects, null and undefined values are not copied.

Static Methods

• Message.install(func,name[,priority[,filterName[,filterValue[,params]]])

Install a Yate message handler.
Parameters:
func - Function to be called when a message is received
name - Message name
priority - Message handler priority (integer). Must be at least 0. Defaults to 100 if not given.
filterName - Message handler parameter filter name. May be a MatchingItem object containing message parameter(s) matching (filterValue will be ignored).
filterValue - Message handler parameter filter value. Simple data (not object) or RegExp.
params - Handler parameters (object).
Return: true on success, false on failure.

Callback function definition: function some_function_name(msg)
params may include an id parameter. If it does subsequent install of a message handler with the same id value will replace an existing one.

• Message.installSingleton(func,handlerContext,name[,priority[,filterName[,filterValue[,params]]])

Install a Yate message handler.
Callback function will be called using a separate script context (data) for each handled message.
The context will be deleted after message handling returns.
Parameters:
func - Function to be called when a message is received
handlerContext - Handler context (string). Wiil be passed as second parameter to callback function.
name - Message name
priority - Message handler priority (integer). Must be at least 0. Defaults to 100 if not given.
filterName - Message handler parameter filter name. May be a MatchingItem object containing message parameter(s) matching (filterValue will be ignored).
filterValue - Message handler parameter filter value. Simple data (not object) or RegExp.
params - Handler parameters (object).
Return: true on success, false on failure.

Callback function definition: function some_function_name(msg,handlerContext)
params may include an load_extensions boolean parameter. Extensions (external, non native, objects) will not be loaded into script context. This may lead to a faster processing if extensions are not needed.
Calling this function will replace an existing handler with the same handlerContext value regardless message name.

• Message.installPostHook(func,id[,filterMsg[,filterName[,filterValue[,params]]]])
• Message.installPostHookSingleton(func,id[,filterMsg[,filterName[,filterValue[,params]]]])

Install a Yate message post hook handler.
Post hook handlers are called after a message is dispatched before returning to entity dispatching the message.
Message object is read only (frozen), can't be changed, you can only read its parameters.
Singleton: Callback function will be called using a separate script context (data) for each handled message. The context will be deleted after message handling returns.
Parameters:
func - Function to be called when a message is handled
id - Handler context (string). Will be passed as second parameter to callback function.
filterMsg -
filterName - Handler parameter filter name. May be a MatchingItem object containing message parameter(s) matching (filterValue will be ignored).
filterValue - Message handler parameter filter value. Simple data (not object) or RegExp.
params - Handler parameters (object).
Return: true on success, false on failure.

• Message.uninstall([nameOrId[,byId]])

• Message.uninstallSingleton(id)

• Message.uninstallPostHook(id)

• Message.handlers()
• Message.handlers(match)

Parameters:
match - Optional string or RegExp used to match only some handler names
Return:
Array of objects describing installed handlers, null if no handler matches.

• name - String name of the handled messages
• priority - Integer priority of the installed handler
• handler - String name of the handling function
• filterName - String name of the filtering parameter (only if a filter is installed)
• filterValue - String value of the filtering parameter (only if a filter is installed)
• trackName - String name of the handler used in tracking (only if not empty)

• Message.installHook()

• Message.uninstallHook()

• Message.trackName()

Return:
Message handler(s) track name value

• Message.trackName(name[,trackPrio])

Parameters:
name - Message track name to be set in new message handlers
trackPrio - Add handler priority to track name. Default: true

Methods

• enqueue([func[,reserved,parameters...]])

Enqueues the Message in the Yate engine
Parameters:
func - Optional function to be called after message is dispatch. Function won't be called if enqueue() fails
reserved - Parameter reserved for future use
parameters - Optional parameters to be passed to callback function
Return: True if enqueue succeeded, false on failure.

NOTE: Message object will become invalid after enqueued. Subsequent functions call will fail or raise a runtime error.

Callback function definition:
function some_func_name(msg,accepted[,parameters...])
Parameters:
msg - Enqueued message. Parameters may change during dispatch
accepted - Boolean indicating message was accepted (handled) or not
parameters - Optional parameters received on enqueue

• dispatch()
• dispatch(unblock)

Parameters:
unblock - Optional boolean flag to unblock context variables during dispatch
Return: True if message was handled, false if it was not handled

NOTES on message dispatch without unblocking the context:

1. Will prevent script processing of other callbacks: message handling, timer callbacks
2. Leads to deadlock if script have a handler for the dispatched message
3. Script unload will wait until context is unblocked

• name()

Return: String name of the message

• broadcast()

Return: Boolean broadcast flag

• getParam(name)
• getParam(name,defValue)
• getParam(name,defValue,autoNumber)

Parameters:
name - Name of the parameter to retrieve
defValue - Value to return if parameter is missing, default undefined
autoNumber - Automatically convert parameters to boolean or number type, default true
Return: Value of parameter, even if name matches a method name

• setParam(name,value)

Parameters:
name - Name of the parameter to set
value - New value to set in parameter, undefined to delete the parameter
Return: True on success, false if message was not in a state where parameters can be changed

• clearParam(name[,sep)

Parameters:
name - Name of the parameter to clear
sep - Optional name separator (first character only)
Return: True on success, false if message was not in a state where parameters can be changed, undefined if name is not given

• copyParams(obj,prefix,skip)

Parameters:
obj - object from which to copy properties (except objects, null and undefined)
prefix - optional parameter to specify that only properties that a key with the given index should be copied. If the prefix represents an object, the properties of that object will be copied.
skip - optional parameter (assumed, by default, to be true) to specifies if the prefix should be copied or eliminated from the key being copied.

• retValue()

Return: Returned value of the message

• retValue(value)

Parameters:
value - New returned value to set in the message

• msgTime()

Return: Message creation time in milliseconds since EPOCH, null if message is not valid

• msgTime(value)

Parameters:
value - Message creation time in milliseconds since EPOCH. Boolean true to set current time
Return: True if message creation time changed, false otherwise

• msgAge()

Return: Message age in milliseconds

• getColumn([indexOrName])

Retrieve one or all columns from message user data table.
Message user data is set after a database query. Database query result contains field names and query result data (values).
Parameters:
indexOrName - Optional column numeric index or name
Return:
null if given column index or name is not found or result set is empty
Column given: array with column values
Otherwise: Object with all result set data. Object property names are set to field names. Object property values are array with column values.

• getRow([index)

Retrieve one or all rows from message user data table.
Message user data is set after a database query. Database query result contains field names and query result data (values).
Parameters:
index - Optional row numeric index
Return:
null if given row index is not found or result set is empty
Row given: Object. Object property names are set to field names. Object property values are field values.
Otherwise: Array of objects. Each object is a row.

• getResult(rowIndex,columnIndexOrName)

Retrieve a value from message user data table.
Message user data is set after a database query. Database query result contains field names and query result data (values).
Parameters:
rowIndex - Row numeric index
columnIndexOrName - Column numeric index or name
Return:
Found value or null if cell given by row/column is not found or result set is empty