Requests configuration parameters from a device. A configuration is split into three separate sources:
- current: Current settings running in the device. The concept of current can vary device by device and setting group by setting group. For instance, the current settings for a serial port are the initial settings of the port (the application opening the port can change the serial port settings via IOCTLs once it has opened the port—this temporal change happens outside of the configuration mechanism). Once the port is open, setting the current settings for serial changes the initial settings, not the actual running settings of the open port.
When current configuration settings differ from running values, we recommend exposing the current values using a <query_state> command group.
- stored: Value used on the next device reboot.
- default: Value present following a <set_factory_default> command.
Sending a <query_setting> without children returns all configuration information for a device, and the complete device configuration is returned. You can use a full <query_setting> reply as a backup of the full configuration of a device.
The settings returned by <query_setting> are arranged in a set of groups called setting groups which logically group associated configuration settings. The children of <query_setting> are setting groups.
The children of settings groups are field value pairs which make up the actual configuration. Values are typed and are declared in the RCI descriptor. See About RCI descriptors for a list of available types.
Optionally, field value pairs can be grouped together when appropriate. These groupings are called a list. Alternatively, if an element X inside a setting group has child elements, then element X is a list. Lists should not be nested more than one deep.
The following attributes are optional but recommended in device implementations. If a device does not support an attribute, it must behave as if the attribute is ignored and not return an error solely because of an unknown attribute.
Supported attributes must be declared in the RCI descriptor. Devices can also add other attributes specific to their device. All attributes must be declared in the RCI descriptor.
The source attribute lets a user request the settings from a particular source. Supported source values:
- “current”: Current running settings.
- “stored”: Configuration stored persistently. This is the configuration that will be used by the device if it is rebooted.
- “defaults”: Default configuration of the device. This is the configuration that will be used if <set_factory_default> is issued.
The default is “current.”
The compare_to attribute works with the source attribute to return only the differences from the compare_to settings and the settings source specified in source. For example, to return only the settings that are different from defaults, issue this request:
<query_setting source=”current” compare_to=”defaults”/>
Supported compare_to values include:
- “none”: No difference requested. Return all values as specified in source.
- “current”: The current running settings.
- “stored”: The configuration stored persistently. This is the configuration used by the device if it is rebooted.
- “defaults”: The default configuration of the device. This is the configuration used if <set_factory_default> is issued. The default value is compare_to=”none”
<rci_request version=”1.1”> <query_setting/> </rci_request> <rci_reply version=”1.1” <query_setting> <serial index=”1”> <!—setting group “serial”, serial port# 1--> <baud>300</baud> <!—field, value pair (baud, 300) --> <stop>2</stop> </serial> <serial index=”2”> <baud>1200</baud> <stop>1</stop> </serial> <routing> <!—setting group “routing”, index # 1 implied --> <in_ip>22.214.171.124</in_ip> <acl index=”1”> <!—ACL is a list, array position #1 --> <allowed>tom, john</allowed> <deny>fred</fred> </acl> <acl index=”2”> <allow>bill</allow> <deny>betty</deny> </acl> </routing> </query_setting> <rci_reply>