Configuration API

RSS

Elve configuration is traditionally done by a user with Elve management Studio. However some configuration can also be done be software developers programatically using the Configuration class.

The machine using the API must either:

Be the same machine running the Elve Master Service.
or have a MachineSettings.config file here: C:\ProgramData\Codecore Technologies\Elve\MachineSettings.config

Table of Contents [Hide/Show]

Example
Configuration Class Members
   Constructors
      Configuration( string username, string password )
   Instance Methods
      SaveDevice( DeviceConfiguration deviceConfig )
      SaveDevice( string originalDeviceName, DeviceConfiguration deviceConfig )
      RemoveDevice( string deviceName )
      EnableDevice( string deviceName )
      DisableDevice( string deviceName )
      GetDeviceConfiguration( string deviceName )
      GetAllDeviceConfigurations()
      GetDeviceConfigurations( params string[] deviceNames )
DeviceConfiguration Class Members
   Constructors
      DeviceConfiguration(string serverName, string name, IEnumerable aliases, string displayName, string driverName, DeviceSettingDictionary settings, bool enabled, LoggerVerbosity verbosity)

Example

Here is a quick example:


using CodecoreTechnologies.Elve.Configuration;
using CodecoreTechnologies.Elve.RemoteAccess;
    
Configuration config;
try
{
    config = new Configuration("admin", "admin");
}
catch (SocketException ex)
{
    // TODO: failed to connect to master service
}
catch (Exception ex)
{
    // TODO: user account does not have access
}

try
{
    // Prepare the device settings
    DeviceSettingDictionary settings = new DeviceSettingDictionary();
    settings.Add("HostName", "192.168.0.12");
    settings.Add("Port", 2101");

    DeviceConfiguration devConfig = new DeviceConfiguration("WINDOWSPC", "elkm1", new string[]{"security", "climate"}, "Elk M1", "ElkM1Driver", settings, true, LoggerVerbosity.Normal)

    // Save the new device
    config.SaveDevice( devConfig );

    // Remove a device
    config.RemoveDevice("lighting");
}
catch (SocketException ex)
{
    // TODO: failed to connect to master service
}
catch (Exception ex)
{
    // TODO: a variety of other exceptions may occur, for example if an argument is invalid, etc.
}

Configuration Class Members

The Configuration class provides support for adding and removing devices from the Elve system programatically. Access to this class is restricted to Elve user accounts which have a user type of System Operator or Administrator.

The server does validate the method parameters but some parameters are not validated until the device is started. So for example if you save a new device but do not include a required setting, the device will fail to start.

Constructors

Configuration( string username, string password )

Initializes the Configuration object. The specified user account must have a user type of Elve System Operator or Administrator.

Syntax

Configuration( string username, string password )

Parameters

username: The username.

password: The password.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

Exception : The user account does not have access, the client configuration file could not be read, or the communications layer could not be set up.

Instance Methods

SaveDevice( DeviceConfiguration deviceConfig )

Saves a device to the Elve system.

Syntax

void SaveDevice( DeviceConfiguration deviceConfig )

Parameters

deviceConfig : The device configuration object.

Return Value

none

Exceptions

SocketException : Failed to fully communicate with the Master Service.

ArgumentException : A DeviceConfiguration property has an invalid value.

FormatException : An DeviceConfiguration property has an invalid format.

SaveDevice( string originalDeviceName, DeviceConfiguration deviceConfig )

Saves a device to the Elve system and replaces an existing device.

Syntax

void SaveDevice( string originalDeviceName, DeviceConfiguration deviceConfig )

Parameters

originalDeviceName : The name of the device to replace. (null if the device is new.)

deviceConfig : The device configuration object.

Return Value

none

Exceptions

SocketException : Failed to fully communicate with the Master Service.

ArgumentException : A DeviceConfiguration property has an invalid value.

FormatException : An DeviceConfiguration property has an invalid format.

RemoveDevice( string deviceName )

Removes a device from the Elve system.

Syntax

void RemoveDevice( string deviceName )

Parameters

deviceName : The name of the device to remove.

Return Value

none

Exceptions

SocketException: Failed to fully communicate with the Master Service.

EnableDevice( string deviceName )

Enable a device.

Syntax

void EnableDevice( string deviceName )

Parameters

deviceName : The name of the device to enable.

Return Value

none

Exceptions

SocketException: Failed to fully communicate with the Master Service.

DisableDevice( string deviceName )

Enable a device.

Syntax

void DisableDevice( string deviceName )

Parameters

deviceName : The name of the device to disable.

Return Value

none

Exceptions

SocketException: Failed to fully communicate with the Master Service.

GetDeviceConfiguration( string deviceName )

Gets the configuration for a specified device.

Syntax

DeviceConfiguration GetDeviceConfiguration(string deviceName)

Parameters

deviceName : The device name to return the configuration.

Return Value

The device configuration for the specified device name.

Exceptions

SocketException: Failed to fully communicate with the Master Service.

GetAllDeviceConfigurations()

Gets the configuration for a all devices.

Syntax

DeviceConfiguration[] GetAllDeviceConfigurations()

Parameters

non

Return Value

The device configuration for all device names

Exceptions

SocketException: Failed to fully communicate with the Master Service.

GetDeviceConfigurations( params string[] deviceNames )

Gets the configuration for one or more specified devices.

Syntax

DeviceConfiguration[] GetDeviceConfiguration(string deviceNames)

Parameters

deviceNames : The device names to return the configuration.

Return Value

The device configuration for the specified device names.

Exceptions

SocketException: Failed to fully communicate with the Master Service.

DeviceConfiguration Class Members

The DeviceConfiguration class represents an Elve device driver instance configuration.

Constructors

DeviceConfiguration(string serverName, string name, IEnumerable aliases, string displayName, string driverName, DeviceSettingDictionary settings, bool enabled, LoggerVerbosity verbosity)

Instantiates the DeviceConfiguration object.

Syntax

DeviceConfiguration(string serverName, string name, IEnumerable aliases, string displayName, string driverName, DeviceSettingDictionary settings, bool enabled, LoggerVerbosity verbosity)

Parameters

serverName : The NetBIOS computer name of the Windows machine that this device should run on.

name : The unique identifier name of the device which the device can be referenced by in scripts.

aliases : A list of alias device names.

displayName : Any display name or description of the device.

driverName : The short type name of the driver class. Do not include the namespace.

settings : A dictionary of settings for the device.

enabled : Indicates if the device is enabled. Devices which are not enabled will not be run.

verbosity : Indicates the logging verbosity that the device should use. This is usually Normal or Diagnostics.

Exceptions

FormatException : A parameter has an invalid format.