| | |
- cd(...)
- cd(sock, path) -> None
Changes the working directory according to the format path. Note that
this function can not be used as an existence test.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to cd to
- cli_diff_iterate(...)
- Function is deprecated.
- close(...)
- close(sock) -> None
Closes the socket. end_session() should be called before calling this
function.
Keyword arguments:
sock -- a previously connected CDB socket
- connect(...)
- connect(sock, type, ip, port, path) -> None
The application has to connect to NCS before it can interact. There are two
different types of connections identified by the type argument -
DATA_SOCKET and SUBSCRIPTION_SOCKET.
Keyword arguments:
sock -- a Python socket instance
type -- DATA_SOCKET or SUBSCRIPTION_SOCKET
ip -- the ip address if socket is AF_INET (optional)
port -- the port if socket is AF_INET (optional)
path -- a filename if socket is AF_UNIX (optional).
- connect_name(...)
- connect_name(sock, type, name, ip, port, path) -> None
When we use connect() to create a connection to NCS/CDB, the name
argument passed to the library initialization function confd_init() (see
confd_lib_lib(3)) is used to identify the connection in status reports and
logs. I we want different names to be used for different connections from
the same application process, we can use connect_name() with the wanted
name instead of connect().
Keyword arguments:
sock -- a Python socket instance
type -- DATA_SOCKET or SUBSCRIPTION_SOCKET
name -- the name
ip -- the ip address if socket is AF_INET (optional)
port -- the port if socket is AF_INET (optional)
path -- a filename if socket is AF_UNIX (optional).
- create(...)
- create(sock, path) -> None
Create a new list entry, presence container, or leaf of type empty. Note
that for list entries and containers, sub-elements will not exist until
created or set via some of the other functions, thus doing implicit
create via set_object() or set_values() may be preferred in this case.
Keyword arguments:
sock -- a previously connected CDB socket
path -- item to create (string)
- delete(...)
- delete(sock, path) -> None
Delete a list entry, presence container, or leaf of type empty, and all
its child elements (if any).
Keyword arguments:
sock -- a previously connected CDB socket
path -- item to delete (string)
- diff_iterate(...)
- diff_iterate(sock, subid, iter, flags, initstate) -> int
After reading the subscription socket the diff_iterate() function can be
used to iterate over the changes made in CDB data that matched the
particular subscription point given by subid.
The user defined function iter() will be called for each element that has
been modified and matches the subscription.
This function will return the last return value from the iter() callback.
Keyword arguments:
sock -- a previously connected CDB socket
subid -- the subcscription id
iter -- iterator function (see below)
initstate -- opaque passed to iter function
The user defined function iter() will be called for each element that has
been modified and matches the subscription. It must have the following
signature:
iter_fn(kp, op, oldv, newv, state) -> int
Arguments:
kp - a HKeypathRef or None
op - the operation
oldv - the old value or None
newv - the new value or None
state - the initstate object
- diff_iterate_resume(...)
- diff_iterate_resume(sock, reply, iter, resumestate) -> int
The application must call this function whenever an iterator function has
returned ITER_SUSPEND to finish up the iteration. If the application does
not wish to continue iteration it must at least call
diff_iterate_resume(sock, ITER_STOP, None, None) to clean up the state.
The reply parameter is what the iterator function would have returned
(i.e. normally ITER_RECURSE or ITER_CONTINUE) if it hadn't returned
ITER_SUSPEND.
This function will return the last return value from the iter() callback.
Keyword arguments:
sock -- a previously connected CDB socket
reply -- the reply value
iter -- iterator function (see diff_iterate())
resumestate -- opaque passed to iter function
- diff_match(...)
- Function not yet implemented.
- end_session(...)
- end_session(sock) -> None
We use connect() to establish a read socket to CDB. When the socket is
closed, the read session is ended. We can reuse the same socket for another
read session, but we must then end the session and create another session
using start_session().
Keyword arguments:
sock -- a previously connected CDB socket
- exists(...)
- exists(sock, path) -> bool
Leafs in the data model may be optional, and presence containers and list
entries may or may not exist. This function checks whether a node exists
in CDB.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to check for existence
- get(...)
- get(sock, path) -> _lib.Value
This reads a a value from the path and returns the result. The path must
lead to a leaf element in the XML data tree.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to leaf
- get_case(...)
- get_case(sock, choice, path) -> None
When we use the YANG choice statement in the data model, this function
can be used to find the currently selected case, avoiding useless
get() etc requests for elements that belong to other cases.
Keyword arguments:
sock -- a previously connected CDB socket
choice -- the choice (string)
path -- path to container or list entry where choice is defined (string)
- get_modifications(...)
- get_modifications(sock, subid, flags, path) -> list
The get_modifications() function can be called after reception of a
subscription notification to retrieve all the changes that caused the
subscription notification. The socket sock is the subscription socket. The
subscription id must also be provided. Optionally a path can be used to
limit what is returned further (only changes below the supplied path will
be returned), if this isn't needed path can be set to None.
Keyword arguments:
sock -- a previously connected CDB socket
subid -- subscription id
flags -- the flags
path -- a path in string format or None
- get_modifications_cli(...)
- get_modifications_cli(sock, subid, flags) -> string
The get_modifications_cli() function can be called after reception of
a subscription notification to retrieve all the changes that caused the
subscription notification as a string in Cisco CLI format. The socket sock
is the subscription socket. The subscription id must also be provided.
Keyword arguments:
sock -- a previously connected CDB socket
subid -- subscription id
flags -- the flags
- get_modifications_iter(...)
- get_modifications_iter(sock, flags) -> list
The get_modifications_iter() is basically a convenient short-hand of
the get_modifications() function intended to be used from within a
iteration function started by diff_iterate(). In this case no subscription
id is needed, and the path is implicitly the current position in the
iteration.
Keyword arguments:
sock -- a previously connected CDB socket
flags -- the flags
- get_object(...)
- get_object(sock, n, path) -> list
This function reads at most n values from the container or list entry
specified by the path, and returns them as a list of Value's.
Keyword arguments:
sock -- a previously connected CDB socket
n -- max number of values to read
path -- path to a list entry or a container (string)
- get_objects(...)
- get_objects(sock, n, ix, nobj, path) -> list
Similar to get_object(), but reads multiple entries of a list based
on the "instance integer" otherwise given within square brackets in the
path - here the path must specify the list without the instance integer.
At most n values from each of nobj entries, starting at entry ix, are
read and placed in the values array. The return value is a list of objects
where each object is represented as a list of Values.
Keyword arguments:
sock -- a previously connected CDB socket
n -- max number of values to read from each object
ix -- start index
nobj -- number of objects to read
path -- path to a list entry or a container (string)
- get_phase(...)
- get_phase(sock) -> dict
Returns the start-phase that CDB is currently in. The return value is a
dict of the form:
{
'phase': phase,
'flags': flags,
'init': init,
'upgrade': upgrade
}
In this dict 'phase' and 'flags' are integers, while 'init' and 'upgrade'
are booleans.
Keyword arguments:
sock -- a previously connected CDB socket
- get_replay_txids(...)
- get_replay_txids(sock) -> list(tuple)
When the subscriptionReplay functionality is enabled in confd.conf this
function returns the list of available transactions that CDB can replay.
The current transaction id will be the first in the list, the second at
txid[1] and so on. In case there are no replay transactions available (the
feature isn't enabled or there hasn't been any transactions yet) only one
(the current) transaction id is returned.
The returned list contains tuples with the form (s1, s2, s3, master) where
s1, s2 and s3 are unsigned integers and master is either a string or None.
Keyword arguments:
sock -- a previously connected CDB socket
- get_transaction_handle(...)
- get_transaction_handle(sock) -> int
Returns the transaction handle for the transaction that triggered the
current subscription notification. This function uses a subscription
socket, and can only be called when a subscription notification for
configuration data has been received on that socket, before
sync_subscription_socket() has been called. Additionally, it is not
possible to call this function from the iter() function passed to
diff_iterate().
Note:
A CDB client is not expected to access the ConfD transaction store
directly - this function should only be used for logging or debugging
purposes.
Note:
When the ConfD High Availability functionality is used, the
transaction information is not available on slave nodes.
Keyword arguments:
sock -- a previously connected CDB socket
- get_txid(...)
- get_txid(sock) -> tuple
Read the last transaction id from CDB. This function can be used if we are
forced to reconnect to CDB. If the transaction id we read is identical to
the last id we had prior to loosing the CDB sockets we don't have to reload
our managed object data. See the User Guide for full explanation.
The returned tuple has the form (s1, s2, s3, master) where s1, s2 and s3
are unsigned integers and master is either a string or None.
Keyword arguments:
sock -- a previously connected CDB socket
- get_user_session(...)
- get_user_session(sock) -> int
Returns the user session id for the transaction that triggered the
current subscription notification. This function uses a subscription
socket, and can only be called when a subscription notification for
configuration data has been received on that socket, before
sync_subscription_socket() has been called. Additionally, it is not
possible to call this function from the iter() function passed to
diff_iterate(). To retrieve full information about the user session,
use _maapi.get_user_session() (see confd_lib_maapi(3)).
Note:
When the ConfD High Availability functionality is used, the
user session information is not available on slave nodes.
Keyword arguments:
sock -- a previously connected CDB socket
- get_values(...)
- get_values(sock, values, path) -> list
Read an arbitrary set of sub-elements of a container or list entry. The
values list must be pre-populated with a number of TagValue instances.
TagValues passed in the values list will be updated with the corresponding
values read and a new values list will be returned.
Keyword arguments:
sock -- a previously connected CDB socket
values -- a list of TagValue instances
path -- path to a list entry or a container (string)
- getcwd(...)
- getcwd(sock) -> string
Returns the current position as previously set by cd(), pushd(), or popd()
as a string path. Note that what is returned is a pretty-printed version of
the internal representation of the current position. It will be the shortest
unique way to print the path but it might not exactly match the string given
to cd().
Keyword arguments:
sock -- a previously connected CDB socket
- getcwd_kpath(...)
- getcwd_kpath(sock) -> _lib.HKeypathRef
Returns the current position like getcwd(), but as a _lib.HKeypathRef
instead of as a string.
Keyword arguments:
sock -- a previously connected CDB socket
- index(...)
- index(sock, path) -> int
Given a path to a list entry index() returns its position (starting from 0).
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to list entry
- initiate_journal_compaction(...)
- initiate_journal_compaction(sock) -> None
Normally CDB handles journal compaction of the config datastore
automatically. If this has been turned off (in the configuration file)
then the A.cdb file will grow indefinitely unless this API function is
called periodically to initiate compaction. This function initiates a
compaction and returns immediately (if the datastore is locked, the
compaction will be delayed, but eventually compaction will take place).
Calling this function when journal compaction is configured to be automatic
has no effect.
Keyword arguments:
sock -- a previously connected CDB socket
- is_default(...)
- is_default(sock, path) -> bool
This function returns True for a leaf which has a default value defined in
the data model when no value has been set, i.e. when the default value is
in effect. It returns False for other existing leafs.
There is normally no need to call this function, since CDB automatically
provides the default value as needed when get() etc is called.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to leaf
- load_file(...)
- load_file(sock, filename, flags) -> None
Load operational data from filename into CDB operational. The file must
be in xml format, and sock must be connected to CDB operational (i.e.
start_session() or start_session2() must have been called with
OPERATIONAL). If the file contains config data, or operational data
not residing in CDB, that data will be silently ignored. If the name of
the file ends in .gz (or .Z) then the file is assumed to be gzipped, and
will be uncompressed as it is loaded.
Note:
If you use a relative pathname for filename, it is taken as relative
to the working directory of the ConfD daemon, i.e. the directory
where the daemon was started.
Note that there are no transactions in CDB operational, so there will not
be any validation or transactional commit of the file. However the file
will be completely parsed before CDB tries to set the values, with the
result that any errors in the file will abort the operation without
changing anything in CDB operational.
The flags parameter is currently not used, and should be set to 0.
Keyword arguments:
sock -- a previously connected CDB socket
filename -- name of the file
flags -- not used - should be set to 0
- load_str(...)
- load_str(sock, xml_str, flags) -> None
Load operational data from the string xml_str into CDB operational. I.e.
instead of having the xml data read from a file as for load_file(),
it is passed as a string to the function. Besides this, the function
works the same as load_file().
Keyword arguments:
sock -- a previously connected CDB socket
xml_str -- name data
flags -- not used - should be set to 0
- mandatory_subscriber(...)
- mandatory_subscriber(sock, name) -> None
Attaches a mandatory attribute and a mandatory name to the subscriber
identified by sock. The name argument is distinct from the name argument
in connect_name().
Keyword arguments:
sock -- a previously connected CDB socket
name -- the name
- next_index(...)
- next_index(sock, path) -> int
Given a path to a list entry next_index() returns the position
(starting from 0) of the next entry (regardless of whether the path
exists or not).
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to list entry
- num_instances(...)
- num_instances(sock, path) -> int
Returns the number of instances in a list.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to list node
- oper_subscribe(...)
- oper_subscribe(sock, nspace, path) -> int
Sets up a CDB subscription for changes in the operational database.
Similar to the subscriptions for configuration data, we can be notified
of changes to the operational data stored in CDB. Note that there are
several differences from the subscriptions for configuration data.
Keyword arguments:
sock -- a previously connected CDB socket
nspace -- the namespace hash
path -- path to node
- popd(...)
- popd(sock) -> None
Pops the top element from the directory stack and changes directory to
previous directory.
Keyword arguments:
sock -- a previously connected CDB socket
- pushd(...)
- pushd(sock, path) -> None
Similar to cd() but pushes the previous current directory on a stack.
Keyword arguments:
sock -- a previously connected CDB socket
path -- path to cd to
- read_subscription_socket(...)
- read_subscription_socket(sock) -> list
This call will return a list of integer values containing subscription
points earlier acquired through calls to subscribe().
Keyword arguments:
sock -- a previously connected CDB socket
- read_subscription_socket2(...)
- read_subscription_socket2(sock) -> tuple
Another version of read_subscription_socket() which will return a 3-tuple
in the form (type, flags, subpoints).
Keyword arguments:
sock -- a previously connected CDB socket
- replay_subscriptions(...)
- replay_subscriptions(sock, txid, sub_points) -> None
This function makes it possible to replay the subscription events for the
last configuration change to some or all CDB subscribers. This call is
useful in a number of recovery scenarios, where some CDB subscribers lost
connection to ConfD before having received all the changes in a
transaction. The replay functionality is only available if it has been
enabled in confd.conf.
Keyword arguments:
sock -- a previously connected CDB socket
txid -- a 4-tuple of the form (s1, s2, s3, master)
sub_points -- a list of subscription points
- set_case(...)
- set_case(sock, choice, scase, path) -> None
When we use the YANG choice statement in the data model, this function
can be used to select the current case.
Keyword arguments:
sock -- a previously connected CDB socket
choice -- the choice (string)
scase -- the case (string)
path -- path to container or list entry where choice is defined (string)
- set_elem(...)
- set_elem(sock, value, path) -> None
Set the value of a single leaf. The value may be either a Value instance or
a string.
Keyword arguments:
sock -- a previously connected CDB socket
value -- the value to set
path -- a string pointing to a single leaf
- set_namespace(...)
- set_namespace(sock, hashed_ns) -> None
If we want to access data in CDB where the toplevel element name is not
unique, we need to set the namespace. We are reading data related to a
specific .fxs file. confdc can be used to generate a .py file with a class
for the namespace, by the flag --emit-python to confdc (see confdc(1)).
Keyword arguments:
sock -- a previously connected CDB socket
hashed_ns -- the namespace hash
- set_object(...)
- set_object(sock, values, path) -> None
Set all elements corresponding to the complete contents of a container or
list entry, except for sub-lists.
Keyword arguments:
sock -- a previously connected CDB socket
values -- a list of Value:s
path -- path to container or list entry (string)
- set_timeout(...)
- set_timeout(sock, timeout_secs) -> None
A timeout for client actions can be specified via
/confdConfig/cdb/clientTimeout in confd.conf, see the confd.conf(5)
manual page. This function can be used to dynamically extend (or shorten)
the timeout for the current action. Thus it is possible to configure a
restrictive timeout in confd.conf, but still allow specific actions to
have a longer execution time.
Keyword arguments:
sock -- a previously connected CDB socket
timeout_secs -- timeout in seconds
- set_values(...)
- set_values(sock, values, path) -> None
Set arbitrary sub-elements of a container or list entry.
Keyword arguments:
sock -- a previously connected CDB socket
values -- a list of TagValue:s
path -- path to container or list entry (string)
- start_session(...)
- start_session(sock, db) -> None
Starts a new session on an already established socket to CDB. The db
parameter should be one of RUNNING, PRE_COMMIT_RUNNING, STARTUP and
OPERATIONAL.
Keyword arguments:
sock -- a previously connected CDB socket
db -- the database
- start_session2(...)
- start_session2(sock, db, flags) -> None
This function may be used instead of start_session() if it is considered
necessary to have more detailed control over some aspects of the CDB
session - if in doubt, use start_session() instead. The sock and db
arguments are the same as for start_session(), and these values can be used
for flags (ORed together if more than one).
Keyword arguments:
sock -- a previously connected CDB socket
db -- the database
flags - the flags
- sub_abort_trans(...)
- sub_abort_trans(sock, code, apptag_ns, apptag_tag, reason) -> None
This function is to be called instead of sync_subscription_socket()
when the subscriber wishes to abort the current transaction. It is only
valid to call after read_subscription_socket2() has returned with
type set to CDB_SUB_PREPARE. The arguments after sock are the same as to
X_seterr_extended() and give the caller a way of indicating the
reason for the failure.
Keyword arguments:
sock -- a previously connected CDB socket
code -- the error code
apptag_ns -- the namespace hash
apptag_tag -- the tag hash
reason -- reason string
- sub_abort_trans_info(...)
- sub_abort_trans_info(sock, code, apptag_ns, apptag_tag, error_info, reason) -> None
Same a sub_abort_trans() but also fills in the NETCONF <error-info> element.
Keyword arguments:
sock -- a previously connected CDB socket
code -- the error code
apptag_ns -- the namespace hash
apptag_tag -- the tag hash
error_info -- a list of TagValue instances
reason -- reason string
- sub_progress(...)
- sub_progress(sock, msg) -> None
After receiving a subscription notification (using
read_subscription_socket()) but before acknowledging it (or aborting,
in the case of prepare subscriptions), it is possible to send progress
reports back to ConfD using the sub_progress() function.
Keyword arguments:
sock -- a previously connected CDB socket
msg -- the message
- subscribe(...)
- subscribe(sock, prio, nspace, path) -> int
Sets up a CDB subscription so that we are notified when CDB configuration
data changes. There can be multiple subscription points from different
sources, that is a single client daemon can have many subscriptions and
there can be many client daemons. The return value is a subscription point
used to identify this particular subscription.
Keyword arguments:
sock -- a previously connected CDB socket
prio -- priority
nspace -- the namespace hash
path -- path to node
- subscribe2(...)
- subscribe2(sock, type, flags, prio, nspace, path) -> int
This function supersedes the current subscribe() and oper_subscribe() as
well as makes it possible to use the new two phase subscription method.
Keyword arguments:
sock -- a previously connected CDB socket
type -- subscription type
flags -- flags
prio -- priority
nspace -- the namespace hash
path -- path to node
- subscribe_done(...)
- subscribe_done(sock) -> None
When a client is done registering all its subscriptions on a particular
subscription socket it must call subscribe_done(). No notifications will be
delivered until then.
Keyword arguments:
sock -- a previously connected CDB socket
- sync_subscription_socket(...)
- sync_subscription_socket(sock, st) -> None
Once we have read the subscription notification through a call to
read_subscription_socket() and optionally used the diff_iterate()
to iterate through the changes as well as acted on the changes to CDB, we
must synchronize with CDB so that CDB can continue and deliver further
subscription messages to subscribers with higher priority numbers.
Keyword arguments:
sock -- a previously connected CDB socket
st -- sync type (int)
- trigger_oper_subscriptions(...)
- trigger_oper_subscriptions(sock, sub_points, flags) -> None
This function works like trigger_subscriptions(), but for CDB
subscriptions to operational data. The caller will trigger all
subscription points passed in the sub_points list (or all operational
data subscribers if the list is empty), and the call will not return until
the last subscriber has called sync_subscription_socket().
Keyword arguments:
sock -- a previously connected CDB socket
sub_points -- a list of subscription points
flags -- the flags
- trigger_subscriptions(...)
- trigger_subscriptions(sock, sub_points) -> None
This function makes it possible to trigger CDB subscriptions for
configuration data even though the configuration has not been modified.
The caller will trigger all subscription points passed in the sub_points
list (or all subscribers if the list is empty) in priority order, and the
call will not return until the last subscriber has called
sync_subscription_socket().
Keyword arguments:
sock -- a previously connected CDB socket
sub_points -- a list of subscription points
- wait_start(...)
- wait_start(sock) -> None
This call waits until CDB has completed start-phase 1 and is available,
when it is CONFD_OK is returned. If CDB already is available (i.e.
start-phase >= 1) the call returns immediately. This can be used by a CDB
client who is not synchronously started and only wants to wait until it
can read its configuration. The call can be used after connect().
Keyword arguments:
sock -- a previously connected CDB socket
|