Javascript Message

Latest revision as of 10:40, 10 September 2024

Yate Message object

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

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

Multiple handlers and post hooks may be installed for the same message using same or different callback, priority, filter.
Multiple handlers and post hooks may be installed for different messages using same callback.

[edit] 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.

[edit] 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[,id])
Parameters:
msg - Message to be handled.
id - Non empty handler id if set on install.

Handler parameters (set 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) set on install.
  

Handler parameters (set in params):

• load_extensions - boolean. Load extensions (external, non native, objects) into script context.
  Not loading extensions may lead to a faster processing.
  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 object.
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) set in install.
  

Post hook parameters (passed in params):

• load_extensions - boolean. Load extensions (external, non native, objects) into script context.
  Not loading extensions may lead to a faster processing.
  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).
  
• handled - boolean. Callback function call based on message handled value (callback function will not be called if value of this parameter is not the same as meesage handled value).
  Default if missing or empty: always call the given callback.
  This parameter is ignored for broadcasted messages.
  

• 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 see MatchingItem.getDesc().
  
• filter - Message parameter(s) match. Object. Properties: see MatchingItem.getDesc().
  
• 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.
  
• handled - PostHook only (boolean). Message handled filter state. Present if set 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

[edit] Methods

• enqueue([callback[,params,callback_args...]])

Enqueues the Message in the Yate engine
Parameters:
callback - 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
params - Parameter reserved for future use
callback_args - 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,handled[,callback_args...])
Parameters:
msg - Enqueued message. Parameters may change during dispatch
handled - Boolean indicating message was accepted (handled) or not
parameters - Optional parameters passed on enqueue() function call

Enqueue parameters (set in params):

• handled - boolean. Callback function call based on message handled value (callback function will not be called if value of this parameter is not the same as meesage handled value).
  Default if missing or empty: always call the given callback.
  This parameter is ignored for broadcasted messages.
  

• 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