| Overview |  |
Copyright © 2006 Tail-F Systems AB
Version: {$Id$}
An Erlang interface equivalent to the confd_lib_dp C-API (documented in confd_lib_dp(3)).
This module is used to connect to ConfD and provide callback functions so that ConfD can populate its northbound agent interfaces with external data. Thus the library consists of a number of API functions whose purpose is to install different callback functions at different points in the XML tree which is the representation of the device configuration. Read more about callpoints in the ConfD User Guide.cb_action() = cb_action_act() | cb_action_cmd()
It is the callback for #confd_action_cb.action
cb_action_act() = fun((U::#confd_user_info{}, Name::qtag(), KP::ikeypath(), [Param::tagval()]) -> ok) | {ok, [Result::tagval()]} | {error, error_reason()}
It is the callback for #confd_action_cb.action when invoked as an action request.
cb_action_cmd() = fun((U::#confd_user_info{}, Name::binary(), Path::binary(), [Arg::binary()]) -> ok) | {ok, [Result::binary()]} | {error, error_reason()}
It is the callback for #confd_action_cb.action when invoked as a CLI command callback.
cb_authentication() = fun((#confd_authentication_ctx{}) -> ok) | error | {error, binary()}
The callback for #confd_authentication_cb.auth
cb_candidate_commit() = fun((#confd_db_ctx{}, Timeout::integer()) -> ok) | {error, error_reason()}
The callback for #confd_db_cbs.candidate_commit
cb_create() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> ok) | {error, error_reason()} | delayed_response
It is the callback for #confd_data_cbs.create. Only used when we use external database config data, e.g. not for statistics.
cb_ctx() = fun((#confd_trans_ctx{}) -> ok) | {ok, #confd_trans_ctx{}} | {error, error_reason()}
The callback for #confd_trans_validate_cbs.init and #confd_trans_cbs.init as well as several other callbacks in #confd_trans_cbs{}
cb_db() = fun((#confd_db_ctx{}, DbName::integer()) -> ok) | {error, error_reason()}
The callback for #confd_db_cbs.lock, #confd_db_cbs.unlock, and #confd_db_cbs.delete_config
cb_exists_optional() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.exists_optional. The exists_optional callback must be present if our YANG model has presence containers or leafs of type empty.
cb_find_next() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), FindNextType::integer(), PrevKey::key()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.find_next.
cb_find_next_object() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), FindNextType::integer(), PrevKey::key()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {ok, Objects, TimeoutMillisecs::integer()} | {ok, Objects, TimeoutMillisecs::integer(), #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
Optional callback which combines the functionality of find_next() and get_object(), and adds the possibility to return multiple objects. It is the callback for #confd_data_cbs.find_next_object. For a detailed description of the two forms of the value list, please refer to the "Value Array" and "Tag Value Array" specifications, respectively, in the XML STRUCTURES section of the confd_types(3) manual page.
cb_get_attrs() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), [Attr::integer()]) -> {ok, [{Attr::integer(), V::value()}]}) | {ok, not_found} | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.get_attrs.
cb_get_elem() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.get_elem.
cb_get_log_times() = fun((#confd_notification_ctx{}) -> {ok, {Created::datetime(), Aged::datetime() | not_found}}) | {error, error_reason()}
The callback for #confd_notification_stream_cbs.get_log_times
cb_get_next() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), Prev::term()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.get_next. Prev is the integer -1 on the first call.
cb_get_next_object() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), Prev::term()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {ok, Objects, TimeoutMillisecs::integer()} | {ok, Objects, TimeoutMillisecs::integer(), #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
Optional callback which combines the functionality of get_next() and get_object(), and adds the possibility to return multiple objects. It is the callback for #confd_data_cbs.get_next_object. For a detailed description of the two forms of the value list, please refer to the "Value Array" and "Tag Value Array" specifications, respectively, in the XML STRUCTURES section of the confd_types(3) manual page.
cb_get_object() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
Optional callback which is used to return an entire object. It is the callback for #confd_data_cbs.get_object. For a detailed description of the two forms of the value list, please refer to the "Value Array" and "Tag Value Array" specifications, respectively, in the XML STRUCTURES section of the confd_types(3) manual page.
cb_lock_partial() = fun((#confd_db_ctx{}, DbName::integer(), LockId::integer(), [ikeypath()]) -> ok) | {error, error_reason()}
The callback for #confd_db_cbs.lock_partial
cb_move_after() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), PrevKeys::{value()}) -> ok) | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.move_after. PrevKeys == {} means that the list entry should become the first one.
cb_num_instances() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> {ok, Reply}) | {ok, Reply, #confd_trans_ctx{}} | {error, error_reason()} | delayed_response
Optional callback, if it doesn't exist it will be emulated by consecutive calls to get_next(). It is the callback for #confd_data_cbs.num_instances.
cb_ok() = fun((#confd_trans_ctx{}) -> ok) | {error, error_reason()}
The callback for #confd_trans_cbs.finish and #confd_trans_validate_cbs.stop
cb_ok_db() = fun((#confd_db_ctx{}) -> ok) | {error, error_reason()}
The callback for #confd_db_cbs.candidate_confirming_commit and several other callbacks in #confd_db_cbs{}
cb_remove() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> ok) | {error, error_reason()} | delayed_response
It is the callback for #confd_data_cbs.remove. Only used when we use external database config data, e.g. not for statistics.
cb_replay() = fun((#confd_notification_ctx{}, Start::datetime(), Stop::datetime() | undefined) -> ok) | {error, error_reason()}
The callback for #confd_notification_stream_cbs.replay
cb_set_attr() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), Attr::integer(), Value) -> ok) | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.set_attr. Value == undefined means that the attribute should be deleted.
cb_set_elem() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), Value::value()) -> ok) | {error, error_reason()} | delayed_response
It is the callback for #confd_data_cbs.set_elem. Only used when we use external database config data, e.g. not for statistics.
cb_str_to_val() = fun((TypeCtx::term(), String::string()) -> {ok, Value::value()}) | error | {error, Reason::binary()} | none()
The callback for #confd_type_cbs.str_to_val. The TypeCtx argument is currently unused (passed as 'undefined'). The function may fail - this is equivalent to returning 'error'.
cb_trans_lock() = fun((#confd_trans_ctx{}) -> ok) | {ok, #confd_trans_ctx{}} | {error, error_reason()} | confd_already_locked
The callback for #confd_trans_cbs.trans_lock. The confd_already_locked return value is equivalent to {error, #confd_error{ code = in_use }}.
cb_unlock_partial() = fun((#confd_db_ctx{}, DbName::integer(), LockId::integer()) -> ok) | {error, error_reason()}
The callback for #confd_db_cbs.unlock_partial
cb_val_to_str() = fun((TypeCtx::term(), Value::value()) -> {ok, String::string()}) | error | {error, Reason::binary()} | none()
The callback for #confd_type_cbs.val_to_str. The TypeCtx argument is currently unused (passed as 'undefined'). The function may fail - this is equivalent to returning 'error'.
cb_validate() = fun((T::#confd_trans_ctx{}, KP::ikeypath(), Newval::value()) -> ok) | {error, error_reason()} | {validation_warn, Reason::binary()}
It is the callback for #confd_valpoint_cb.validate.
cb_validate_value() = fun((TypeCtx::term(), Value::value()) -> ok) | error | {error, Reason::binary()} | none()
The callback for #confd_type_cbs.validate. The TypeCtx argument is currently unused (passed as 'undefined'). The function may fail - this is equivalent to returning 'error'.
cb_write() = fun((#confd_trans_ctx{}) -> ok) | {ok, #confd_trans_ctx{}} | {error, error_reason()} | confd_in_use
The callback for #confd_trans_cbs.write_start and #confd_trans_cbs.prepare. The confd_in_use return value is equivalent to {error, #confd_error{ code = in_use }}.
cb_write_all() = fun((T::#confd_trans_ctx{}, KP::ikeypath()) -> ok) | {error, error_reason()} | delayed_response
This is the callback for #confd_data_cbs.write_all. The KP argument is currently always [], since the callback does not pertain to any particular data node.
completion_action() = fun((U::#confd_user_info{}, CliStyle::int(), Token::binary(), CompletionChar::int(), IKP::ikeypath(), CmdPath::binary(), Id::binary(), TP::term(), Extra::term()) -> [string() | {info, string()} | {desc, string()} | default])
datetime() = {C_DATETIME::integer(), DateAndTime}
The value representation for yang:date-and-time, also used in the API functions for notification streams.
namespace() = atom()
socket() = port() | int_ipc:sock()
tagpath() = [qtag()]
A tagpath() is a list describing a path down into the schema tree.
I.e. as opposed to an ikeypath(), it has no instance information.
Additionally the last (top) element is not [NS|XmlTag] as in
ikeypath(), but only XmlTag - i.e. it needs to be combined with
a namespace to uniquely identify a schema node. The other elements
in the path are qualified - or not - exactly as for ikeypath().
tagval() = {qtag(), value() | start | stop | leaf | {start, Index::integer()}}
This is used to represent XML elements together with their values, typically in a list representing an XML subtree as in the arguments and result of the 'action' callback. Typeless elements have the special "values" 'start' (opening container or list element), 'stop' (closing container or list element), 'leaf' (leaf with type "empty"), or {start, Index} (opening list element with CDB Index instead of key value(s) - only valid for CDB access). The qtag() tuple element may have the namespace()-less form (i.e. tag()) for XML elements in the "current" namespace. For a detailed description of how to represent XML as a list of tagval() elements, please refer to the "Tagged Value Array" specification in the XML STRUCTURES section of the confd_types(3) manual page.
type() = term()
Identifies a type definition in the schema.
| action_set_timeout/2 | Extend (or shorten) the timeout for the current action callback invocation. |
| controlling_process/2 | Assigns a new controlling process Pid to Socket. |
| data_reply_error/2 | Reply an error for delayed_response. |
| data_reply_found/1 | Reply 'found' for delayed_response. |
| data_reply_next_key/3 | Reply with next key for delayed_response. |
| data_reply_next_object_tag_value_array/3 | Reply with tagged values and next key for delayed_response. |
| data_reply_next_object_value_array/3 | Reply with values and next key for delayed_response. |
| data_reply_next_object_value_arrays/3 | Reply with multiple objects, each with values and next key, plus cache timeout, for delayed_response. |
| data_reply_not_found/1 | Reply 'not found' for delayed_response. |
| data_reply_ok/1 | Reply 'ok' for delayed_response. |
| data_reply_tag_value_array/2 | Reply a list of tagged values for delayed_response. |
| data_reply_value/2 | Reply a value for delayed_response. |
| data_reply_value_array/2 | Reply a list of values for delayed_response. |
| data_set_timeout/2 | Extend (or shorten) the timeout for the current callback invocation. |
| decrypt/1 | Decrypts a value of type tailf:des3-cbc-encrypted-string or tailf:aes-cfb-128-encrypted-string. |
| init_daemon/6 | Starts and links to a gen_server which connects to ConfD. |
| log/2 | Logs Fmt to devel.log if running internal, otherwise to standard out. |
| log/3 | Logs Fmt with Args to devel.log if running internal, otherwise to standard out. |
| log/4 | Logs Fmt with Args to devel.log if running internal, otherwise to IoDevice. |
| notification_replay_complete/1 | Call this function when replay is done. |
| notification_replay_failed/2 | Call this function when replay has failed for some reason. |
| notification_send/3 | Send an XML notification. |
| pp_kpath/1 | Pretty print an ikeypath. |
| pp_value/1 | Pretty print a value. |
| register_action_cb/2 | Register action callback on an actionpoint. |
| register_authentication_cb/2 | Register authentication callback. |
| register_data_cb/2 | Register the data callbacks. |
| register_db_cbs/2 | Register extern db callbacks. |
| register_done/1 | This function must be called when all callback registrations are done. |
| register_notification_stream/2 | Register notif callbacks on an streamname. |
| register_range_data_cb/5 | Register data callbacks for a range of keys. |
| register_trans_cb/2 | Register transaction phase callbacks. |
| register_trans_validate_cb/2 | Register validation transaction callback. |
| register_valpoint_cb/2 | Register validation callback on a valpoint. |
| set_daemon_d_opaque/2 | Set the d_opaque field in the daemon which is typically used by the callbacks. |
| set_debug/3 | Change the DebugLevel and/or Estream for a running daemon. |
| start/0 | Starts the econfd application. |
| stop_daemon/1 | Silently stop a daemon. |
action_set_timeout(Uinfo::#confd_user_info{}, Seconds::integer()) -> ok | {error, Reason::term()}
Extend (or shorten) the timeout for the current action callback invocation. The timeout is given in seconds from the point in time when the function is called.
controlling_process(Socket::term(), Pid::pid()) -> ok | {error, Reason::term()}
Assigns a new controlling process Pid to Socket
data_reply_error(Tctx::#confd_trans_ctx{}, Error::error_reason()) -> ok | {error, Reason::term()}
Reply an error for delayed_response. Like data_reply_value() - only used in combination with delayed_response.
data_reply_found(Tctx::#confd_trans_ctx{}) -> ok | {error, Reason::term()}
Reply 'found' for delayed_response. Like data_reply_value() - only used in combination with delayed_response.
data_reply_next_key(Tctx::#confd_trans_ctx{}, Key, Next::term()) -> ok | {error, Reason::term()}
Reply with next key for delayed_response. Like data_reply_value() - only used in combination with delayed_response.
data_reply_next_object_tag_value_array(Tctx::#confd_trans_ctx{}, Values::[TV::tagval()], Next::term()) -> ok | {error, Reason::term()}
Reply with tagged values and next key for delayed_response. Like data_reply_value() - only used in combination with delayed_response, and get_next_object() callback.
data_reply_next_object_value_array(Tctx::#confd_trans_ctx{}, Values, Next::term()) -> ok | {error, Reason::term()}
Reply with values and next key for delayed_response. Like data_reply_value() - only used in combination with delayed_response, and get_next_object() callback.
data_reply_next_object_value_arrays(Tctx::#confd_trans_ctx{}, Objects, TimeoutMillisecs::integer()) -> ok | {error, Reason::term()}
Reply with multiple objects, each with values and next key, plus cache timeout, for delayed_response. Like data_reply_value() - only used in combination with delayed_response, and get_next_object() callback.
data_reply_not_found(Tctx::#confd_trans_ctx{}) -> ok | {error, Reason::term()}
Reply 'not found' for delayed_response. Like data_reply_value() - only used in combination with delayed_response.
data_reply_ok(Tctx::#confd_trans_ctx{}) -> ok | {error, Reason::term()}
Reply 'ok' for delayed_response. This function can be used explicitly by the erlang application if a data callback returns the atom delayed_response. In that case it is the responsibility of the application to later invoke one of the data_reply_xxx() functions. If delayed_response is not used, none of the explicit data replying functions need to be used.
data_reply_tag_value_array(Tctx::#confd_trans_ctx{}, TagVals::[tagval()]) -> ok | {error, Reason::term()}
Reply a list of tagged values for delayed_response. Like data_reply_value() - only used in combination with delayed_response, and get_object() callback.
data_reply_value(Tctx::#confd_trans_ctx{}, V::value()) -> ok | {error, Reason::term()}
Reply a value for delayed_response. This function can be used explicitly by the erlang application if a data callback returns the atom delayed_response. In that case it is the responsibility of the application to later invoke one of the data_reply_xxx() functions. If delayed_response is not used, none of the explicit data replying functions need to be used.
data_reply_value_array(Tctx::#confd_trans_ctx{}, Values) -> ok | {error, Reason::term()}
Reply a list of values for delayed_response. Like data_reply_value() - only used in combination with delayed_response, and get_object() callback.
data_set_timeout(Tctx::#confd_trans_ctx{}, Seconds::integer()) -> ok | {error, Reason::term()}
Extend (or shorten) the timeout for the current callback invocation. The timeout is given in seconds from the point in time when the function is called.
decrypt(X1::binary()) -> {ok, binary()} | {error, {Ecode::integer(), Reason::binary()}}
Decrypts a value of type tailf:des3-cbc-encrypted-string or tailf:aes-cfb-128-encrypted-string. Requires that econfd_maapi:install_crypto_keys/1 has been called in the node.
init_daemon(Name::atom(), DebugLevel::integer(), Estream::io_device(), Dopaque::term(), Ip::ip(), Port::integer()) -> {ok, Pid::pid()} | {error, Reason::term()}
Starts and links to a gen_server which connects to ConfD. This gen_server holds two sockets to ConfD, one so called control socket and one worker socket (See confd_lib_dp(3) for an explanation of those sockets.)
The gen_server is used to install sets of callback Funs. The gen_server state is a #confd_daemon_ctx{}. This structure is passed to all the callback functions.
The daemon context includes a d_opaque element holding the Dopaque term - this can be used by the application to pass application specific data into the callback functions.
The Name::atom() parameter is used in various debug printouts and is also used to uniquely identify the daemon.
The DebugLevel parameter is used to control the debug level. The following levels are available:
log(Level::integer(), Fmt::string()) -> ok
Logs Fmt to devel.log if running internal, otherwise to standard out. Level can be one of ?CONFD_LEVEL_ERROR | ?CONFD_LEVEL_INFO | ?CONFD_LEVEL_TRACE
log(Level::integer(), Fmt::string(), Args::list()) -> ok
Logs Fmt with Args to devel.log if running internal, otherwise to standard out. Level can be one of ?CONFD_LEVEL_ERROR | ?CONFD_LEVEL_INFO | ?CONFD_LEVEL_TRACE
log(IoDevice::io:device(), Level::integer(), Fmt::string(), Args::list()) -> ok
Logs Fmt with Args to devel.log if running internal, otherwise to IoDevice. Level can be one of ?CONFD_LEVEL_ERROR | ?CONFD_LEVEL_INFO | ?CONFD_LEVEL_TRACE
notification_replay_complete(Nctx::#confd_notification_ctx{}) -> ok | {error, Reason::term()}
Call this function when replay is done
notification_replay_failed(Nctx::#confd_notification_ctx{}, ErrorString::binary()) -> ok | {error, Reason::term()}
Call this function when replay has failed for some reason
notification_send(Nctx::#confd_notification_ctx{}, DateTime::datetime(), TagVals::[tagval()]) -> ok | {error, Reason::term()}
Send an XML notification.
pp_kpath(IKP::ikeypath()) -> io_list()
Pretty print an ikeypath.
Pretty print a value.
register_action_cb(Daemon::pid(), ActionCbs::#confd_action_cb{}) -> ok | {error, Reason::term()}
Register action callback on an actionpoint
register_authentication_cb(Daemon::pid(), AuthenticationCb::#confd_authentication_cb{}) -> ok | {error, Reason::term()}
Register authentication callback. Note, this can not be used to *perform* the authentication.
register_data_cb(Daemon::pid(), DbCbs::#confd_data_cbs{}) -> ok | {error, Reason::term()}
Register the data callbacks.
register_db_cbs(Daemon::pid(), DbCbs::#confd_db_cbs{}) -> ok | {error, Reason::term()}
Register extern db callbacks.
register_done(Daemon::pid()) -> ok | {error, Reason::term()}
This function must be called when all callback registrations are done
register_notification_stream(Daemon::pid(), NotifCbs::#confd_notification_stream_cbs{}) -> {ok, #confd_notification_ctx{}} | {error, Reason::term()}
Register notif callbacks on an streamname
register_range_data_cb(Daemon::pid(), DataCbs::#confd_data_cbs{}, Lower::[Lower::value()], Higher::[Higher::value()], IKP::ikeypath()) -> ok | {error, Reason::term()}
Register data callbacks for a range of keys.
register_trans_cb(Daemon::pid(), TransCbs::#confd_trans_cbs{}) -> ok | {error, Reason::term()}
Register transaction phase callbacks. See confd_lib_dp(3) for a thorough description of the transaction phases. The record #confd_trans_cbs{} contains callbacks for all of the phases for a transaction. If we use this external data api only for statistics data only the init() and the finish() callbacks should be used. The init() callback must return 'ok', {error, String}, or {ok, Tctx} where Tctx is the same #confd_trans_ctx that was supplied to the init callback but possibly with the opaque field filled in. This field is meant to be used by the user to manage user data.
register_trans_validate_cb(Daemon::pid(), ValidateCbs::#confd_trans_validate_cbs{}) -> ok | {error, Reason::term()}
Register validation transaction callback. This function maps an init and a finish function for validations. See seme function in confd_lib_dp(3) The init() callback must return 'ok', {error, String}, or {ok, Tctx} where Tctx is the same #confd_trans_ctx that was supplied to the init callback but possibly with the opaque field filled in.
register_valpoint_cb(Daemon::pid(), ValpointCbs::#confd_valpoint_cb{}) -> ok | {error, Reason::term()}
Register validation callback on a valpoint
set_daemon_d_opaque(Daemon::pid(), Dopaque::term()) -> ok
Set the d_opaque field in the daemon which is typically used by the callbacks
set_debug(Daemon::pid(), DebugLevel::integer(), Estream::io_device()) -> ok
Change the DebugLevel and/or Estream for a running daemon
start() -> ok | {error, Reason::term()}
Starts the econfd application.
stop_daemon(Daemon::pid()) -> ok
Silently stop a daemon
Generated by EDoc, Mar 21 2017, 11:19:34.