Javascript Message

Revision as of 13:21, 2 September 2024

Yate Message object

Singleton functions (installSingleton, uninstallSingleton, handlersSingleton, installPostHookSingleton, posthooksSingleton) are not available:

• Singleton contexts (when a singleton message is handled): handler or post hook
  
• Temporary scripts (executed using the javascript eval command)
  
• Script instance grater than 1 for scripts configured with multiple instances. These functions are available in first instance only
  

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 some_function_name(msg)

Handler parameters (passed in params):
id - Optional handler id (string). Install of a message handler with the same (non empty) 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.
Calling this function will replace an existing handler with the same handlerContext value regardless message name.
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 some_function_name(msg,handlerContext)
Parameters:

• msg - Message to handle.
  
• handlerContext - Singleton context (string) passed on install.
  

Handler parameters (passed in params):

• load_extensions - boolean. Extensions (external, non native, objects) will not be loaded into script context.
  This may lead to a faster processing if extensions are not needed.
  Extensions are never loaded if message name matches script.init.
  

• 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.
The module maintains a single list of post hooks. Installing a post hook with a given id will replace an existing one (singleton or not).

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 - Optional message name match. May be a string, RegExp or MatchingItem for complex match.
filterName - Message parameter filter name. May be a MatchingItem object containing message parameter(s) matching (filterValue will be ignored).
filterValue - Message parameter filter value. Simple data (not object) or RegExp.
params - Parameters (object) Return: true on success, false on failure.

Callback: function some_function_name(msg,handled,id)
Parameters:

• msg - Message. Object is frozen.
  
• handled - True if message was handled, false otherwise.
  
• id - Post hook id (string) passed in install.
  

Post hook parameters (passed in params):

• load_extensions - boolean. Extensions (external, non native, objects) will not be loaded into script context.
  This may lead to a faster processing if extensions are not needed.
  Extensions are never loaded if message name matches script.init.
  
• engine.timer - boolean. Process engine.timer message.
  Default to false if filterMsg is set (assume engine.timer match is set there if desired).
  

• Message.uninstall()

Uninstall all message handler(s) including singleton(s).

• Message.uninstall(nameOrId[,byId])

Uninstall a regular (non singleton) message handler.
Parameters:

• nameOrId - String. Value used to match the handler.
  
• byId - Boolean. Match by handler id (true) or name (false). Default: false.
  

• Message.uninstallSingleton(id)

Uninstall a singleton message handler.
Parameters:

• id - Id of message to uninstall (string).
  

• Message.uninstallPostHook(id)

Uninstall a message post hook.
Parameters:

• id - Id of post hook to uninstall (string).
  

• Message.handlers([match])
• Message.handlersSingleton([match])
• Message.posthooks()
• Message.posthooksSingleton()

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

• name - Handler only. Name of the handled message (string).
  
• priority - Handler only. Integer priority of the installed handler.
  
• msg_filter - Post hook only: message name match. Object. Properties: see MatchingItem dscription.
  
• filter - Message parameter(s) match. Object. Properties: see MatchingItem dscription.
  
• handler - Name of the handling function (string).
  
• trackName - Handler only. Name of the handler used in tracking (only if not empty). Format: track_name[:priority].
  
• message_context - Singleton handler only: handler context.
  
• id - Handler/PostHook id (string). Singleton handler: same as message context. Regular (non singleton) handler: present if given on install.
  

• 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 dispatched. Function is called before passing the message to internal message post hook(s). 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 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 passed on enqueue() function call

• 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