base/bif/option.bif.bro

GLOBAL

Option

Definitions of built-in functions that allow the scripting layer to change the value of options and to be notified when option values change.

Namespaces:GLOBAL, Option Source File:/scripts/base/bif/option.bif.bro

Summary

Functions

Option::set: function	Set an option to a new value.
Option::set_change_handler: function	Set a change handler for an option.

Detailed Interface

Functions

Option::set

Type:function (ID: string, val: any, location: string &default = "" &optional) : bool

Set an option to a new value. This change will also cause the option change handlers to be called.

ID:The ID of the option to update. Val:The new value of the option. Location:Optional parameter detailing where this change originated from. Returns:true on success, false when an error occurred.

See also: Option::set_change_handler, Config::set_value

Note

Option::set only works on one node and does not distribute new values across a cluster. The higher-level Config::set_value supports clusterization and should typically be used instead of this lower-level function.

Option::set_change_handler

Type:function (ID: string, on_change: any, priority: int &default = 0 &optional) : bool

Set a change handler for an option. The change handler will be called anytime Option::set is called for the option.

ID:The ID of the option for which change notifications are desired. On_change:The function that will be called when a change occurs. The function can choose to receive two or three parameters: the first parameter is a string containing ID, the second parameter is the new option value. The third, optional, parameter is the location string as passed to Option::set. Note that the global value is not yet changed when the function is called. The passed function has to return the new value that it wants the option to be set to. This enables it to reject changes, or change values that are being set. When several change handlers are set for an option they are chained; the second change handler will see the return value of the first change handler as the “new value”. Priority:The priority of the function that was added; functions with higher priority are called first, functions with the same priority are called in the order in which they were added. Returns:true when the change handler was set, false when an error occurred.

See also: Option::set