Interface IHsController

C#
Visual Basic

[Obfuscation(Exclude = true, ApplyToMembers = true)]
[ScsService]
public interface IHsController

Namespace: HomeSeer.PluginSdk

Assembly: PluginSdk.dll

The interface used by plugins to communicate with the HomeSeer software

An instance of this interface is automatically provided to an AbstractPlugin when AbstractPlugin.Connect(string[]) is called.

Properties

View Source

APIVersion

The current version of the HomeSeer Plugin API

double APIVersion { get; }

Property Value

Type	Description
System.Double

View Source

DeviceCount

The number of devices connected to the HomeSeer system

Declaration

C#
Visual Basic

int DeviceCount { get; }

Property Value

Type	Description
System.Int32

View Source

EventCount

The number of events configured on the HomeSeer system

Declaration

C#
Visual Basic

int EventCount { get; }

Property Value

Type	Description
System.Int32

Remarks

PLEASE NOTE: This was ported directly from the legacy HS3 API and has not been fully reviewed to ensure proper compatibility and support through this SDK. This may undergo significant change in the near future. Please use with caution.

View Source

SolarNoon

Get the DateTime for Solar Noon from the HomeSeer system

Declaration

C#
Visual Basic

DateTime SolarNoon { get; }

Property Value

Type	Description
System.DateTime

View Source

Sunrise

Get the DateTime for Sunrise from the HomeSeer system

Declaration

C#
Visual Basic

DateTime Sunrise { get; }

Property Value

Type	Description
System.DateTime

View Source

Sunset

Get the DateTime for Sunset from the HomeSeer system

Declaration

C#
Visual Basic

DateTime Sunset { get; }

Property Value

Type	Description
System.DateTime

Methods

View Source

AddActionRunScript(Int32, String, String, String)

Declaration

C#
Visual Basic

void AddActionRunScript(int ref, string script, string method, string parms)

Parameters

Type	Name	Description
System.Int32	ref
System.String	script
System.String	method
System.String	parms

Remarks

View Source

AddDeviceActionToEvent(Int32, ControlEvent)

Declaration

C#
Visual Basic

string AddDeviceActionToEvent(int evRef, ControlEvent CC)

Parameters

Type	Name	Description
System.Int32	evRef
ControlEvent	CC

Returns

Type	Description
System.String

Remarks

View Source

AddRefsToCategory(String, List<Int32>)

Add a collection of refs to a category

Declaration

C#
Visual Basic

List<int> AddRefsToCategory(string id, List<int> devRefs)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.Collections.Generic.List<System.Int32>	devRefs	A list of refs to add to the category

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	The current list of refs on the category after adding the ones specified

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

AddRefToCategory(String, Int32)

Add a ref to a category

Declaration

C#
Visual Basic

List<int> AddRefToCategory(string id, int devRef)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.Int32	devRef	The ref to add to the category

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	The current list of refs on the category after adding the one specified

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

AddStatusControlToFeature(Int32, StatusControl)

Add a StatusControl to the collection of StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

void AddStatusControlToFeature(int featRef, StatusControl statusControl)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update
StatusControl	statusControl	The StatusControl to add

View Source

AddStatusGraphicToFeature(Int32, StatusGraphic)

Add a StatusGraphic to the collection of StatusGraphics associated with an HsFeature

Declaration

C#
Visual Basic

void AddStatusGraphicToFeature(int featRef, StatusGraphic statusGraphic)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update
StatusGraphic	statusGraphic	The StatusGraphic to add

View Source

CheckRegistrationStatus(String)

Get the ERegistrationMode of a plugin

Declaration

C#
Visual Basic

int CheckRegistrationStatus(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin to read

Returns

Type	Description
System.Int32	The ERegistrationMode of the plugin with the specified ID

View Source

ClearIniSection(String, String)

Clear all of the settings saved in a section in a specific file

Declaration

C#
Visual Basic

void ClearIniSection(string sectionName, string fileName)

Parameters

Type	Name	Description
System.String	sectionName	The section to clear
System.String	fileName	The name of the INI file to edit

View Source

ClearStatusControlsByRef(Int32)

Delete all StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

void ClearStatusControlsByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update

View Source

ClearStatusGraphicsByRef(Int32)

Delete all StatusGraphics associated with an HsFeature

Declaration

C#
Visual Basic

void ClearStatusGraphicsByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update

View Source

CreateCategory(String, String)

Create a new category with the specified name and image path

Declaration

C#
Visual Basic

string CreateCategory(string name, string image)

Parameters

Type	Name	Description
System.String	name	The display name of the category
System.String	image	The path to the image for the category. Use the files in /html/images/Categories/

Returns

Type	Description
System.String	The ID of the newly created category

Exceptions

Type	Condition
System.ArgumentException	Thrown when the name is already in use by another category

View Source

CreateDevice(NewDeviceData)

Create a new device in HomeSeer

Declaration

C#
Visual Basic

int CreateDevice(NewDeviceData deviceData)

Parameters

Type	Name	Description
NewDeviceData	deviceData	NewDeviceData describing the device produced by DeviceFactory

Returns

Type	Description
System.Int32	The unique reference ID assigned to the device

View Source

CreateEventWithNameInGroup(String, String)

Create a new event with a specific name in a particular group

Declaration

C#
Visual Basic

int CreateEventWithNameInGroup(string name, string group)

Parameters

Type	Name	Description
System.String	name	The name of the new event
System.String	group	The group to add the event to

Returns

Type	Description
System.Int32	The Ref of the new event

Remarks

View Source

CreateFeatureForDevice(NewFeatureData)

Create a new feature on a device in HomeSeer

Declaration

C#
Visual Basic

int CreateFeatureForDevice(NewFeatureData featureData)

Parameters

Type	Name	Description
NewFeatureData	featureData	NewFeatureData describing the feature produced by FeatureFactory

Returns

Type	Description
System.Int32	The unique reference ID assigned to the feature

View Source

CreateVar(String)

Create a new global variable

Declaration

C#
Visual Basic

string CreateVar(string name)

Parameters

Type	Name	Description
System.String	name	The name of the global variable

Returns

Type	Description
System.String	An empty string no error occured, or an error string if one did occur.

View Source

DecryptString(String, String, String)

Decrypt a string using a decryption password that you specify.

Declaration

C#
Visual Basic

string DecryptString(string text, string password, string keyModifier = "")

Parameters

Type	Name	Description
System.String	text	The text to decrypt
System.String	password	The user-created text string to decrypt the text with
System.String	keyModifier	The modifier used with the password to create the decryption key. If EncryptString was used with a key modifier was, you must specify the same key modifier here.

Returns

Type	Description
System.String	A string containing a decrypted form of the text parameter, decrypted using password (and keyModifier if provided)

View Source

DeleteAfterTrigger_Clear(Int32)

Declaration

C#
Visual Basic

void DeleteAfterTrigger_Clear(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef

Remarks

View Source

DeleteAfterTrigger_Set(Int32)

Declaration

C#
Visual Basic

void DeleteAfterTrigger_Set(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef

Remarks

View Source

DeleteCategoryById(String)

Delete a category by ID

Declaration

C#
Visual Basic

void DeleteCategoryById(string id)

Parameters

Type	Name	Description
System.String	id	The ID of the category to delete

View Source

DeleteDevice(Int32)

Delete the HsDevice with the specified Ref and all other AbstractHsDevices associated with it.

Declaration

C#
Visual Basic

bool DeleteDevice(int devRef)

Parameters

Type	Name	Description
System.Int32	devRef	The Ref of the HsDevice to delete

Returns

Type	Description
System.Boolean	TRUE if the HsDevice was deleted, FALSE if there was an error. Check the HS logs for more info on the error.

Exceptions

Type	Condition
System.ArgumentException	Thrown when the specified `devRef` refers to a HsFeature and not a HsDevice.

View Source

DeleteDevicesByInterface(String)

Delete all devices, and their corresponding features, from the HomeSeer system that are managed by the specified plugin interface

Declaration

C#
Visual Basic

bool DeleteDevicesByInterface(string interfaceName)

Parameters

Type	Name	Description
System.String	interfaceName	The name of the interface that owns all of the devices and features to delete. This is usually the plugin Id

Returns

Type	Description
System.Boolean	TRUE if the delete was successful, FALSE if there was a problem during the process.

View Source

DeleteEventByRef(Int32)

Delete an event

Declaration

C#
Visual Basic

void DeleteEventByRef(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event to delete

Remarks

View Source

DeleteFeature(Int32)

Delete the HsFeature with the specified Ref

Declaration

C#
Visual Basic

bool DeleteFeature(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to delete

Returns

Type	Description
System.Boolean	TRUE if the HsFeature was deleted, FALSE if there was an error. Check the HS logs for more info on the error.

View Source

DeleteImageFile(String)

Delete the specified file from HomeSeer's HTML image directory.

Declaration

C#
Visual Basic

bool DeleteImageFile(string targetFile)

Parameters

Type	Name	Description
System.String	targetFile	The path of the image following "\html\images"

Returns

Type	Description
System.Boolean	TRUE if the file was deleted successfully, FALSE if it still exists

Examples

The following example shows how to delete an image from HomeSeer's HTML image directory.

var filePath = $"{Id}\\sampleImage.png";
if (!HomeSeerSystem.DeleteImageFile(filePath)) {
    Console.WriteLine($"Error deleting {filePath}");
}

DeleteStatusControlByValue(Int32, Double)

Delete a StatusControl in the collection of StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

bool DeleteStatusControlByValue(int featRef, double value)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update
System.Double	value	The value of the StatusControl to delete

Returns

Type	Description
System.Boolean	true if the deletion succeeded, otherwise false

View Source

DeleteStatusGraphicByValue(Int32, Double)

Delete a StatusGraphic in the collection of StatusGraphics associated with an HsFeature

Declaration

C#
Visual Basic

bool DeleteStatusGraphicByValue(int featRef, double value)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update
System.Double	value	The value of the StatusGraphic to delete

Returns

Type	Description
System.Boolean	true if the deletion succeeded, otherwise false

View Source

DeleteVar(String)

Delete a global variable

Declaration

C#
Visual Basic

void DeleteVar(string name)

Parameters

Type	Name	Description
System.String	name	The name of the global variable

View Source

DisableEventByRef(Int32)

Disable an event

Declaration

C#
Visual Basic

void DisableEventByRef(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event to disable

Remarks

View Source

DoesRefExist(Int32)

Determine if a specific device/feature Ref exists in the HomeSeer system

Declaration

C#
Visual Basic

bool DoesRefExist(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Boolean	TRUE if the Ref exists, FALSE if it does not

View Source

EnableEventByRef(Int32)

Enable an event

Declaration

C#
Visual Basic

void EnableEventByRef(int evref)

Parameters

Type	Name	Description
System.Int32	evref	The Ref of the event to enable

Remarks

View Source

Energy_AddCalculator(Int32, String, TimeSpan, TimeSpan)

PLEASE NOTE: Code related to the Energy components in HomeSeer were ported from the HS3 plugin API and have not been fully tested to verify full functionality from the new SDK. The Energy API may undergo significant changes in the near future. Please use with caution.

Declaration

C#
Visual Basic

string Energy_AddCalculator(int dvRef, string Name, TimeSpan Range, TimeSpan StartBack)

Parameters

Type	Name	Description
System.Int32	dvRef
System.String	Name
System.TimeSpan	Range
System.TimeSpan	StartBack

Returns

Type	Description
System.String

View Source

Energy_AddCalculatorEvenDay(Int32, String, TimeSpan, TimeSpan)

Declaration

C#
Visual Basic

string Energy_AddCalculatorEvenDay(int dvRef, string Name, TimeSpan Range, TimeSpan StartBack)

Parameters

Type	Name	Description
System.Int32	dvRef
System.String	Name
System.TimeSpan	Range
System.TimeSpan	StartBack

Returns

Type	Description
System.String

View Source

Energy_AddData(Int32, EnergyData)

Declaration

C#
Visual Basic

bool Energy_AddData(int dvRef, EnergyData Data)

Parameters

Type	Name	Description
System.Int32	dvRef
EnergyData	Data

Returns

Type	Description
System.Boolean

View Source

Energy_AddDataArray(Int32, EnergyData[])

Declaration

C#
Visual Basic

bool Energy_AddDataArray(int dvRef, EnergyData[] colData)

Parameters

Type	Name	Description
System.Int32	dvRef
EnergyData[]	colData

Returns

Type	Description
System.Boolean

View Source

Energy_CalcCount(Int32)

Declaration

C#
Visual Basic

int Energy_CalcCount(int dvRef)

Parameters

Type	Name	Description
System.Int32	dvRef

Returns

Type	Description
System.Int32

View Source

Energy_GetArchiveData(Int32, DateTime, DateTime)

Declaration

C#
Visual Basic

List<EnergyData> Energy_GetArchiveData(int dvRef, DateTime dteStart, DateTime dteEnd)

Parameters

Type	Name	Description
System.Int32	dvRef
System.DateTime	dteStart
System.DateTime	dteEnd

Returns

Type	Description
System.Collections.Generic.List<EnergyData>

View Source

Energy_GetArchiveDatas(String, DateTime, DateTime)

Declaration

C#
Visual Basic

List<EnergyData> Energy_GetArchiveDatas(string dvRefs, DateTime dteStart, DateTime dteEnd)

Parameters

Type	Name	Description
System.String	dvRefs
System.DateTime	dteStart
System.DateTime	dteEnd

Returns

Type	Description
System.Collections.Generic.List<EnergyData>

View Source

Energy_GetCalcByIndex(Int32, Int32)

Declaration

C#
Visual Basic

EnergyCalcData Energy_GetCalcByIndex(int dvRef, int Index)

Parameters

Type	Name	Description
System.Int32	dvRef
System.Int32	Index

Returns

Type	Description
EnergyCalcData

View Source

Energy_GetCalcByName(Int32, String)

Declaration

C#
Visual Basic

EnergyCalcData Energy_GetCalcByName(int dvRef, string Name)

Parameters

Type	Name	Description
System.Int32	dvRef
System.String	Name

Returns

Type	Description
EnergyCalcData

View Source

Energy_GetData(Int32, DateTime, DateTime)

Declaration

C#
Visual Basic

List<EnergyData> Energy_GetData(int dvRef, DateTime dteStart, DateTime dteEnd)

Parameters

Type	Name	Description
System.Int32	dvRef
System.DateTime	dteStart
System.DateTime	dteEnd

Returns

Type	Description
System.Collections.Generic.List<EnergyData>

View Source

Energy_GetEnergyRefs(Boolean)

Declaration

C#
Visual Basic

SortedList<int, string> Energy_GetEnergyRefs(bool GetParentRefs)

Parameters

Type	Name	Description
System.Boolean	GetParentRefs

Returns

Type	Description
System.Collections.Generic.SortedList<System.Int32, System.String>

View Source

Energy_GetGraph(Int32, String, Int32, Int32, String)

Declaration

C#
Visual Basic

Image Energy_GetGraph(int id, string dvRefs, int width, int height, string format)

Parameters

Type	Name	Description
System.Int32	id
System.String	dvRefs
System.Int32	width
System.Int32	height
System.String	format

Returns

Type	Description
System.Drawing.Image

View Source

Energy_GetGraphData(Int32)

Declaration

C#
Visual Basic

EnergyGraphData Energy_GetGraphData(int ID)

Parameters

Type	Name	Description
System.Int32	ID

Returns

Type	Description
EnergyGraphData

View Source

Energy_GetGraphDataIDs()

Declaration

C#
Visual Basic

SortedList<int, string> Energy_GetGraphDataIDs()

Returns

Type	Description
System.Collections.Generic.SortedList<System.Int32, System.String>

View Source

Energy_RemoveData(Int32, DateTime)

Declaration

C#
Visual Basic

int Energy_RemoveData(int dvRef, DateTime dteStart)

Parameters

Type	Name	Description
System.Int32	dvRef
System.DateTime	dteStart

Returns

Type	Description
System.Int32

View Source

Energy_SaveGraphData(EnergyGraphData)

Declaration

C#
Visual Basic

int Energy_SaveGraphData(EnergyGraphData Data)

Parameters

Type	Name	Description
EnergyGraphData	Data

Returns

Type	Description
System.Int32

View Source

Energy_SetEnergyDevice(Int32, Constants.enumEnergyDevice)

Declaration

C#
Visual Basic

bool Energy_SetEnergyDevice(int dvRef, Constants.enumEnergyDevice DeviceType)

Parameters

Type	Name	Description
System.Int32	dvRef
Constants.enumEnergyDevice	DeviceType

Returns

Type	Description
System.Boolean

View Source

EventEnabled(Int32)

Determine if an event is enabled or not

Declaration

C#
Visual Basic

bool EventEnabled(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event

Returns

Type	Description
System.Boolean	TRUE if the event is enabled

Remarks

View Source

EventExistsByRef(Int32)

Determine if an event with a particular Ref exists

Declaration

C#
Visual Basic

bool EventExistsByRef(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event

Returns

Type	Description
System.Boolean	TRUE if an event with the specified Ref exists

Remarks

View Source

EventSetRecurringTrigger(Int32, TimeSpan, Boolean, Boolean)

Declaration

C#
Visual Basic

bool EventSetRecurringTrigger(int evRef, TimeSpan Frequency, bool Once_Per_Hour, bool Reference_To_Hour)

Parameters

Type	Name	Description
System.Int32	evRef
System.TimeSpan	Frequency
System.Boolean	Once_Per_Hour
System.Boolean	Reference_To_Hour

Returns

Type	Description
System.Boolean

Remarks

View Source

EventSetTimeTrigger(Int32, DateTime)

Declaration

C#
Visual Basic

bool EventSetTimeTrigger(int evRef, DateTime DT)

Parameters

Type	Name	Description
System.Int32	evRef
System.DateTime	DT

Returns

Type	Description
System.Boolean

Remarks

View Source

GetActionsByInterface(String)

Get all of the event actions managed by a specific plugin

Declaration

C#
Visual Basic

List<TrigActInfo> GetActionsByInterface(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin If you are targeting a actiona owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `pluginId`

Returns

Type	Description
System.Collections.Generic.List<TrigActInfo>	A list of all of the actions managed by the plugin

Remarks

View Source

GetAllCategories()

Get a Dictionary of all categories on the HomeSeer system where the key is the ID and the value is the name of each category

Declaration

C#
Visual Basic

Dictionary<string, string> GetAllCategories()

Returns

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>	A Dictionary of category names by ID

View Source

GetAllDeviceRefs()

Get a list of all of the device refs present in the HomeSeer system

This does not include refs for features. To get those in addition to these, use GetAllRefs() or call GetAllFeatureRefs() to get a list of just features

Declaration

C#
Visual Basic

List<int> GetAllDeviceRefs()

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	A list of integers corresponding to the device refs managed by the HomeSeer system

View Source

GetAllDevices(Boolean)

Get a list of all of the devices managed by the HomeSeer system without associated features.

WARNING - this is an expensive method to execute and it should be used with the utmost discretion

Declaration

C#
Visual Basic

List<HsDevice> GetAllDevices(bool withFeatures)

Parameters

Type	Name	Description
System.Boolean	withFeatures	TRUE if associated features should be attached to their devices, or FALSE if features should be left out.

Returns

Type	Description
System.Collections.Generic.List<HsDevice>	A list of HsDevices managed by the HomeSeer system with or without associated features linked.

View Source

GetAllEventGroups()

Get the data for all event groups

Declaration

C#
Visual Basic

List<EventGroupData> GetAllEventGroups()

Returns

Type	Description
System.Collections.Generic.List<EventGroupData>	A list of all of the event groups

Remarks

View Source

GetAllEvents()

Get the data for all of the events

Declaration

C#
Visual Basic

List<EventData> GetAllEvents()

Returns

Type	Description
System.Collections.Generic.List<EventData>	A list of all of the events

Remarks

View Source

GetAllFeatureRefs()

Get a list of all of the feature refs present in the HomeSeer system

This does not include refs for devices. To get those in addition to these, use GetAllRefs() or call GetAllDeviceRefs() to get a list of just devices

Declaration

C#
Visual Basic

List<int> GetAllFeatureRefs()

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	A list of integers corresponding to the feature refs managed by the HomeSeer system

View Source

GetAllRefs()

Get a list of all of the device and feature refs present in the HomeSeer system

To get just a list of devices, call GetAllDeviceRefs() or to get a list of features, call GetAllFeatureRefs()

Declaration

C#
Visual Basic

List<int> GetAllRefs()

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	A list of integers corresponding to the device and feature refs managed by the HomeSeer system

View Source

GetAppPath()

Returns the path to the HS executable. Some plugins need this when running remotely

Declaration

C#
Visual Basic

string GetAppPath()

Returns

Type	Description
System.String	The path to the HomeSeer executable

View Source

GetCategoryImageById(String)

Get the image path of a category by its ID

Declaration

C#
Visual Basic

string GetCategoryImageById(string id)

Parameters

Type	Name	Description
System.String	id	The ID of the category

Returns

Type	Description
System.String	The image path of the category. Null if the category doesn't exist. Empty string if there is no image path for that category

View Source

GetCategoryNameById(String)

Get the name of a category by its ID

Declaration

C#
Visual Basic

string GetCategoryNameById(string id)

Parameters

Type	Name	Description
System.String	id	The ID of the category

Returns

Type	Description
System.String	The name of the category. Null or empty string if the category does not exist

View Source

GetDeviceByAddress(String)

Get the AbstractHsDevice as a HsDevice with the specified Address. The Features property will be empty. To include HsFeatures use GetDeviceWithFeaturesByRef(Int32)

Declaration

C#
Visual Basic

HsDevice GetDeviceByAddress(string devAddress)

Parameters

Type	Name	Description
System.String	devAddress	The Address of the AbstractHsDevice to read

Returns

Type	Description
HsDevice	A HsDevice whether it is a Device or Feature

Remarks

Calling this using the Address of a HsFeature may have adverse effects.

View Source

GetDeviceByCode(String)

Get the first AbstractHsDevice found as a HsDevice with the specified Code.

Declaration

C#
Visual Basic

HsDevice GetDeviceByCode(string devCode)

Parameters

Type	Name	Description
System.String	devCode	The Code of the AbstractHsDevice to read

Returns

Type	Description
HsDevice	A HsDevice whether it is a Device or Feature

Remarks

Calling this using the Address of a HsFeature may have adverse effects.

GetDeviceByRef(Int32)

Get the AbstractHsDevice as a HsDevice with the specified Ref. The Features property will be empty. To include HsFeatures use GetDeviceWithFeaturesByRef(Int32)

Declaration

C#
Visual Basic

HsDevice GetDeviceByRef(int devRef)

Parameters

Type	Name	Description
System.Int32	devRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
HsDevice	A HsDevice whether it is a Device or Feature

Remarks

Calling this using the Ref of a HsFeature may have adverse effects.

View Source

GetDeviceWithFeaturesByRef(Int32)

Get the AbstractHsDevice as a HsDevice with the specified Ref. The Features property will be populated with associated features.

Declaration

C#
Visual Basic

HsDevice GetDeviceWithFeaturesByRef(int devRef)

Parameters

Type	Name	Description
System.Int32	devRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
HsDevice	A HsDevice whether it is a Device or Feature

Remarks

Calling this using the Ref of a HsFeature may have adverse effects.

View Source

GetEventByRef(Int32)

Get the data for an event

Declaration

C#
Visual Basic

EventData GetEventByRef(int eventRef)

Parameters

Type	Name	Description
System.Int32	eventRef	The Ref of the event

Returns

Type	Description
EventData	The data of the event

Remarks

View Source

GetEventGroupById(Int32)

Get the data for an event group

Declaration

C#
Visual Basic

EventGroupData GetEventGroupById(int groupRef)

Parameters

Type	Name	Description
System.Int32	groupRef	The Ref of the group

Returns

Type	Description
EventGroupData	The data of the event group

Remarks

View Source

GetEventNameByRef(Int32)

Get the name of the event with the specific Ref

Declaration

C#
Visual Basic

string GetEventNameByRef(int eventRef)

Parameters

Type	Name	Description
System.Int32	eventRef	The Ref of the event to read

Returns

Type	Description
System.String	The name of the event

Remarks

View Source

GetEventRefByName(String)

Get the Ref of an event by name

Declaration

C#
Visual Basic

int GetEventRefByName(string eventName)

Parameters

Type	Name	Description
System.String	eventName	The name of the event to read

Returns

Type	Description
System.Int32	The Ref of the event

Remarks

View Source

GetEventRefByNameAndGroup(String, String)

Get the Ref of an event by its name and the group it is in

Declaration

C#
Visual Basic

int GetEventRefByNameAndGroup(string eventName, string eventGroup)

Parameters

Type	Name	Description
System.String	eventName	The name of the event
System.String	eventGroup	The name of the group

Returns

Type	Description
System.Int32	The Ref of the event

Remarks

View Source

GetEventsByGroup(Int32)

Get all of the events in a particular group

Declaration

C#
Visual Basic

List<EventData> GetEventsByGroup(int groupId)

Parameters

Type	Name	Description
System.Int32	groupId	The Ref of the event group

Returns

Type	Description
System.Collections.Generic.List<EventData>	A list of all of the events in the event group

Remarks

View Source

GetEventTriggerTime(Int32)

Get the DateTime of the last time a specific event was triggered

Declaration

C#
Visual Basic

DateTime GetEventTriggerTime(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event to read

Returns

Type	Description
System.DateTime	The DateTime the event was last triggered

Remarks

View Source

GetEventVoiceCommand(Int32)

Get the voice command attached to an event

Declaration

C#
Visual Basic

string GetEventVoiceCommand(int evRef)

Parameters

Type	Name	Description
System.Int32	evRef	The Ref of the event to read

Returns

Type	Description
System.String	The voice command string set on the event

Remarks

View Source

GetFeatureByAddress(String)

Get the AbstractHsDevice as a HsFeature with the specified Address.

Declaration

C#
Visual Basic

HsFeature GetFeatureByAddress(string featAddress)

Parameters

Type	Name	Description
System.String	featAddress	The Address of the AbstractHsDevice to read

Returns

Type	Description
HsFeature	A HsFeature whether it is a Device or Feature

Remarks

Calling this using the Address of a HsDevice may have adverse effects.

View Source

GetFeatureByCode(String)

Get the first AbstractHsDevice found as a HsFeature with the specified Code.

Declaration

C#
Visual Basic

HsFeature GetFeatureByCode(string featCode)

Parameters

Type	Name	Description
System.String	featCode	The Code of the AbstractHsDevice to read

Returns

Type	Description
HsFeature	A HsFeature whether it is a Device or Feature

Remarks

Calling this using the Address of a HsDevice may have adverse effects.

GetFeatureByRef(Int32)

Get the AbstractHsDevice as a HsFeature with the specified Ref.

Declaration

C#
Visual Basic

HsFeature GetFeatureByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
HsFeature	A HsFeature whether it is a Device or Feature

Remarks

Calling this using the Ref of a HsDevice may have adverse effects.

View Source

GetFirstLocationList()

Get an alpha-sorted list of the location strings marked as first

This is the list of location strings that are marked as first according to IsLocation1First()

Declaration

C#
Visual Basic

List<string> GetFirstLocationList()

Returns

Type	Description
System.Collections.Generic.List<System.String>	A List of the first location strings

View Source

GetFirstLocationName()

Get the name of the first location.

This is the name of the location that is marked as first according to IsLocation1First()

Declaration

C#
Visual Basic

string GetFirstLocationName()

Returns

Type	Description
System.String	The name of the first location

View Source

GetHSEdition()

Get the current edition of HomeSeer that is running

Declaration

C#
Visual Basic

Constants.editions GetHSEdition()

Returns

Type	Description
Constants.editions	The edition of HomeSeer currently running

View Source

GetIniSection(String, String)

Get a key-value map of settings saved in the specified section of the INI file

Declaration

C#
Visual Basic

Dictionary<string, string> GetIniSection(string section, string fileName)

Parameters

Type	Name	Description
System.String	section	The section to get
System.String	fileName	The name of the INI file

Returns

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>	A Dictionary of setting keys and values

View Source

GetINISetting(String, String, String, String)

Get the value of the setting saved to INI file

Declaration

C#
Visual Basic

string GetINISetting(string sectionName, string key, string defaultVal, string fileName = "")

Parameters

Type	Name	Description
System.String	sectionName	The name of the section the setting is saved to
System.String	key	The key of the setting
System.String	defaultVal	A default value to use if the setting was not previously saved
System.String	fileName	The name of the INI file to search

Returns

Type	Description
System.String

View Source

GetIpAddress()

Obtain the IP address the HomeSeer system is accessible through

Declaration

C#
Visual Basic

string GetIpAddress()

Returns

Type	Description
System.String	A string representation of the IP address HomeSeer is running on

View Source

GetLocation1Name()

Get the name of the Location1 location

Declaration

C#
Visual Basic

string GetLocation1Name()

Returns

Type	Description
System.String	The user defined name of Location1

View Source

GetLocation2Name()

Get the name of the Location2 location

Declaration

C#
Visual Basic

string GetLocation2Name()

Returns

Type	Description
System.String	The user defined name of Location2

View Source

GetLocations2List()

Get an alpha-sorted list of Location2 strings

Declaration

C#
Visual Basic

SortedList GetLocations2List()

Returns

Type	Description
System.Collections.SortedList	A SortedList of Location2 location strings

View Source

GetLocationsList()

Get an alpha-sorted list of Location1 strings

Declaration

C#
Visual Basic

SortedList GetLocationsList()

Returns

Type	Description
System.Collections.SortedList	A SortedList of Location1 location strings

View Source

GetNameByRef(Int32)

Get the name of a specific device/feature by its Ref

Declaration

C#
Visual Basic

string GetNameByRef(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.String	The name of the device/feature with the matching Ref

View Source

GetOsType()

Get the type of OS HomeSeer is running on as EOsType

Declaration

C#
Visual Basic

int GetOsType()

Returns

Type	Description
System.Int32	0 = windows, 1 = linux

GetPluginVersionById(String)

Get the version of a particular plugin by its Id. Do not use this for legacy plugins; it will not work.

Declaration

C#
Visual Basic

string GetPluginVersionById(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The Id of the plugin

Returns

Type	Description
System.String	The version of the main dll for the plugin

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when the `pluginId` parameter is null or whitespace
System.Collections.Generic.KeyNotFoundException	Thrown when a plugin with the specified ID is not found in the list of installed plugins

View Source

GetPluginVersionByName(String)

Get the version of a particular plugin by its name. For interfacing with legacy plugins.

Declaration

C#
Visual Basic

string GetPluginVersionByName(string pluginName)

Parameters

Type	Name	Description
System.String	pluginName	The Name of the plugin

Returns

Type	Description
System.String	The version of the main dll for the plugin

Remarks

This is useful for interacting with Legacy plugins that used a name-instance pair for identification instead of a unique ID. You should use GetPluginVersionById(String) if you are trying to interface with HS4 plugins.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when the `pluginName` parameter is null or whitespace
System.Collections.Generic.KeyNotFoundException	Thrown when a plugin with the specified name is not found in the list of installed plugins

View Source

GetPropertyByInterface(String, EProperty, Boolean)

Get a map containing the value of a specific property for every device owned by a particular plugin

Declaration

C#
Visual Basic

Dictionary<int, object> GetPropertyByInterface(string interfaceName, EProperty property, bool deviceOnly = false)

Parameters

Type	Name	Description
System.String	interfaceName	The ID of the plugin that owns the devices
EProperty	property	The EProperty type to read
System.Boolean	deviceOnly	Whether the result should only contain devices or both devices and features

Returns

Type	Description
System.Collections.Generic.Dictionary<System.Int32, System.Object>	A Dictionary of device/feature refs and the value of the EProperty requested

View Source

GetPropertyByRef(Int32, EProperty)

Get the value of the EProperty for the AbstractHsDevice with the specified Ref

Declaration

C#
Visual Basic

object GetPropertyByRef(int devOrFeatRef, EProperty property)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to read
EProperty	property	The EProperty to read

Returns

Type	Description
System.Object	The value of the requested EProperty of the AbstractHsDevice

View Source

GetRefsByCategoryId(String)

Get a list of Refs of devices and features included in the category

Declaration

C#
Visual Basic

List<int> GetRefsByCategoryId(string id)

Parameters

Type	Name	Description
System.String	id	The ID of the category

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	A List of Refs of devices and features included in the category. Null if the category doesn't exist. Empty list if no devices or features are included in the category.

View Source

GetRefsByInterface(String, Boolean)

Get a list of device/feature references that are associated with the specified plugin interface

Declaration

C#
Visual Basic

List<int> GetRefsByInterface(string interfaceName, bool deviceOnly = false)

Parameters

Type	Name	Description
System.String	interfaceName	The ID of the plugin interface to get devices and features for
System.Boolean	deviceOnly	Whether to get refs for devices or both devices and features

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	A list of device/feature reference IDs

View Source

GetSecondLocationList()

Get an alpha-sorted list of the location strings marked as second

This is the list of location strings that are marked as second according to IsLocation1First()

Declaration

C#
Visual Basic

List<string> GetSecondLocationList()

Returns

Type	Description
System.Collections.Generic.List<System.String>	A List of the second location strings

View Source

GetSecondLocationName()

Get the name of the second location.

This is the name of the location that is marked as second according to IsLocation1First()

Declaration

C#
Visual Basic

string GetSecondLocationName()

Returns

Type	Description
System.String	The name of the second location

View Source

GetSpeakerInstanceList()

This function retrieves a comma separated list of host:instance names for Speaker client instances currently connected to HomeSeer.

Declaration

C#
Visual Basic

string GetSpeakerInstanceList()

Returns

Type	Description
System.String	The returned instance list is a comma separated list of host:instance pairs

View Source

GetStatusControlCollectionByRef(Int32)

Get the StatusControlCollection describing all of the StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

StatusControlCollection GetStatusControlCollectionByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
StatusControlCollection	The StatusControlCollection for the HsFeature

View Source

GetStatusControlCountByRef(Int32)

Get the number of StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

int GetStatusControlCountByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Int32	The number of StatusControls for the HsFeature

View Source

GetStatusControlForLabel(Int32, String)

Get the StatusControl for a Label on an HsFeature

Declaration

C#
Visual Basic

StatusControl GetStatusControlForLabel(int featRef, string label)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read
System.String	label	The Label used by the StatusControl

Returns

Type	Description
StatusControl	A StatusControl with the specified Label for the HsFeature

View Source

GetStatusControlForValue(Int32, Double)

Get the StatusControl for a value on an HsFeature

Declaration

C#
Visual Basic

StatusControl GetStatusControlForValue(int featRef, double value)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read
System.Double	value	The Value managed by the StatusControl

Returns

Type	Description
StatusControl	A StatusControl that manages the value specified for the HsFeature

View Source

GetStatusControlsByRef(Int32)

Get a list of StatusControls associated with an HsFeature

Declaration

C#
Visual Basic

List<StatusControl> GetStatusControlsByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Collections.Generic.List<StatusControl>	The list of StatusControls for the HsFeature

View Source

GetStatusControlsForRange(Int32, Double, Double)

Get a list of StatusControls for a range of values on an HsFeature

Declaration

C#
Visual Basic

List<StatusControl> GetStatusControlsForRange(int featRef, double min, double max)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read
System.Double	min	The minimum value of the range
System.Double	max	The maximum value of the range

Returns

Type	Description
System.Collections.Generic.List<StatusControl>	A list of StatusControls for a range of values on the HsFeature

View Source

GetStatusGraphicCountByRef(Int32)

Get the number of StatusGraphics associated with an HsFeature

Declaration

C#
Visual Basic

int GetStatusGraphicCountByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Int32	The number of StatusGraphics for the HsFeature

View Source

GetStatusGraphicForValue(Int32, Double)

Get the StatusGraphic for a value on an HsFeature

Declaration

C#
Visual Basic

StatusGraphic GetStatusGraphicForValue(int featRef, double value)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read
System.Double	value	The Value managed by the StatusGraphic

Returns

Type	Description
StatusGraphic	A StatusGraphic that manages the value specified for the HsFeature

View Source

GetStatusGraphicsByRef(Int32)

Get a list of StatusGraphics associated with an HsFeature

Declaration

C#
Visual Basic

List<StatusGraphic> GetStatusGraphicsByRef(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Collections.Generic.List<StatusGraphic>	The list of StatusGraphics for the HsFeature

View Source

GetStatusGraphicsForRange(Int32, Double, Double)

Get a list of StatusGraphics for a range of values on an HsFeature

Declaration

C#
Visual Basic

List<StatusGraphic> GetStatusGraphicsForRange(int featRef, double min, double max)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the AbstractHsDevice to read
System.Double	min	The minimum value of the range
System.Double	max	The maximum value of the range

Returns

Type	Description
System.Collections.Generic.List<StatusGraphic>

View Source

GetTriggersByInterface(String)

Get all of the triggers managed by a specific plugin

Declaration

C#
Visual Basic

TrigActInfo[] GetTriggersByInterface(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin If you are targeting triggers owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `pluginId`

Returns

Type	Description
TrigActInfo[]	An array of triggers managed by the plugin

Remarks

View Source

GetTriggersByType(String, Int32)

Get all of the triggers of a particular type

Declaration

C#
Visual Basic

TrigActInfo[] GetTriggersByType(string pluginId, int trigId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin that owns the trigger type If you are targeting triggers owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `pluginId`
System.Int32	trigId	The ID of the trigger type

Returns

Type	Description
TrigActInfo[]	An array of trigger data

Remarks

View Source

GetUsers()

Get a list of users and their rights

Declaration

C#
Visual Basic

string GetUsers()

Returns

Type	Description
System.String	a list of users in this format: username\|rights,username2\|rights2...

View Source

GetVar(String)

Find the global variable associated with the name parameter and return it.

Declaration

C#
Visual Basic

object GetVar(string name)

Parameters

Type	Name	Description
System.String	name	The name of the global variable

Returns

Type	Description
System.Object	The global variable saved.

View Source

GetVolume(String)

Get the volume on a speaker client

Declaration

C#
Visual Basic

int GetVolume(string host)

Parameters

Type	Name	Description
System.String	host	The speaker host to speak to in the format host:instance

Returns

Type	Description
System.Int32	Volume level in the range of 0-100

View Source

IsEventLoggingEnabledByRef(Int32)

Determine if logging is enabled on an event

Declaration

C#
Visual Basic

bool IsEventLoggingEnabledByRef(int eventRef)

Parameters

Type	Name	Description
System.Int32	eventRef	The Ref of the event

Returns

Type	Description
System.Boolean	TRUE if logging is enabled for the event

Remarks

View Source

IsFeatureValueValid(Int32)

Determine if the current status value of a HsFeature is considered valid. This calls IsValueValid() on the HsFeature to determine validity.

Declaration

C#
Visual Basic

bool IsFeatureValueValid(int featRef)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to read

Returns

Type	Description
System.Boolean	The result of IsValueValid()

View Source

IsFlagOnRef(Int32, EMiscFlag)

Determine if a EMiscFlag is turned on for a particular AbstractHsDevice

Declaration

C#
Visual Basic

bool IsFlagOnRef(int devOrFeatRef, EMiscFlag miscFlag)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to read
EMiscFlag	miscFlag	The EMiscFlag to read

Returns

Type	Description
System.Boolean	TRUE if the AbstractHsDevice found contains the specified EMiscFlag, FALSE if it doesn't

View Source

IsLicensed()

Determine if the HomeSeer system is licensed using any license, including a trial

Declaration

C#
Visual Basic

bool IsLicensed()

Returns

Type	Description
System.Boolean	TRUE if the HomeSeer system is licensed

View Source

IsLocation1First()

Determine if Location1 is used first on devices/features.

Declaration

C#
Visual Basic

bool IsLocation1First()

Returns

Type	Description
System.Boolean	TRUE if Location1 is used first, FALSE if Location2 is used first

Remarks

By default, Location2 is used as the first logical location when organizing devices/features. For this reason, it is important to check which location is marked as the first location before working with locations.

View Source

IsMediaPlaying(String)

This function checks if the media player is currently playing a selection

Declaration

C#
Visual Basic

bool IsMediaPlaying(string host)

Parameters

Type	Name	Description
System.String	host	Leaving this a null string will apply the command to the first instance HomeSeer finds, otherwise use the hostname of the computer for this command. If more than one instance of the Speaker application is running on "host" then you may need to specify the instance as well in the format host:instance.

Returns

Type	Description
System.Boolean	TRUE if a media selection is currently playing and the sound card is most likely busy, FALSE if a media selection is not playing and the sound is most likely free.

View Source

IsRefDevice(Int32)

Determine if the AbstractHsDevice with the specified Ref is a HsDevice or a HsFeature of a device

Declaration

C#
Visual Basic

bool IsRefDevice(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to read

Returns

Type	Description
System.Boolean	TRUE if the AbstractHsDevice found is a HsDevice, FALSE if it is a HsFeature

View Source

IsRegistered()

Determine if the HomeSeer system is registered using a paid license

Declaration

C#
Visual Basic

bool IsRegistered()

Returns

Type	Description
System.Boolean	TRUE if the HomeSeer system is registered with a paid license

View Source

IsScriptRunning(String)

This function indicates if a specified script is currently running.

Declaration

C#
Visual Basic

bool IsScriptRunning(string scr)

Parameters

Type	Name	Description
System.String	scr	Filename of the script to check.

Returns

Type	Description
System.Boolean	TRUE if the specified script is currently running and FALSE if it doesn't.

View Source

IsSpeakerBusy(String)

This function can let you know if a specific speaker client (host or host:instance) is currently busy speaking or playing WAV audio.

Declaration

C#
Visual Basic

bool IsSpeakerBusy(string host)

Parameters

Type	Name	Description
System.String	host	Leaving this a null string will return the busy status for the first instance HomeSeer finds, otherwise use the hostname of the computer you are interested in determining the busy status of. If more than one instance of the Speaker application is running on "host" then you may need to specify the instance as well in the format host:instance.

Returns

Type	Description
System.Boolean	TRUE indicates that the speaker application instance is busy

View Source

LegacyPluginFunction(String, String, String, Object[])

Execute a specific function declared within a plugin installed on the HomeSeer system. This calls PluginFunction(String, Object[]) on the target plugin.

Declaration

C#
Visual Basic

object LegacyPluginFunction(string plugName, string plugInstance, string procName, object[] params)

Parameters

Type	Name	Description
System.String	plugName	The Name of the plugin that owns the function
System.String	plugInstance	The instance name of the plugin that owns the function
System.String	procName	The name of the function
System.Object[]	params	An array of parameters to pass to the function being called

Returns

Type	Description
System.Object	An object that contains the return value from the function called. You are on your own when it comes to casting this to the right type.

Remarks

This is useful for interacting with Legacy plugins that used a name-instance pair for identification instead of a unique ID. You should use PluginFunction(String, String, Object[]) if you are trying to interface with HS4 plugins.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when either the `plugName` or `procName` parameters are null or whitespace
System.AggregateException	Thrown when there was an error trying to execute the function. Check the enclosed exception for details.

View Source

LegacyPluginPropertyGet(String, String, String)

Get a specific property declared within a plugin installed on the HomeSeer system. This calls PluginPropertyGet(String) on the target plugin.

Declaration

C#
Visual Basic

object LegacyPluginPropertyGet(string plugName, string plugInstance, string propName)

Parameters

Type	Name	Description
System.String	plugName	The Name of the plugin that owns the property
System.String	plugInstance	The instance name of the plugin that owns the property
System.String	propName	The exact name of the property

Returns

Type	Description
System.Object	An object representing the value of the target property

Remarks

This is useful for interacting with Legacy plugins that used a name-instance pair for identification instead of a unique ID. You should use PluginPropertyGet(String, String) if you are trying to interface with HS4 plugins.

View Source

LegacyPluginPropertySet(String, String, String, Object)

Set a specific property declared within a plugin installed on the HomeSeer system. This calls PluginPropertySet(String, Object) on the target plugin

Declaration

C#
Visual Basic

void LegacyPluginPropertySet(string plugName, string plugInstance, string propName, object propValue)

Parameters

Type	Name	Description
System.String	plugName	The Name of the plugin that owns the property
System.String	plugInstance	The instance name of the plugin that owns the property
System.String	propName	The exact name of the property
System.Object	propValue	The value of the property to set. Its type must exactly match the type defined in the plugin.

Remarks

This is useful for interacting with Legacy plugins that used a name-instance pair for identification instead of a unique ID. You should use PluginPropertySet(String, String, Object) if you are trying to interface with HS4 plugins.

View Source

PlayWavFile(String, String, Boolean)

Plays audio from passed file to a specific speaker client

Declaration

C#
Visual Basic

void PlayWavFile(string FileName, string Host, bool Wait)

Parameters

Type	Name	Description
System.String	FileName	The filename can be the full path to the file, or just the name of file that is located in one of the following folders in the HomeSeer root directory: wave/Mdia/scripts
System.String	Host	The speaker host to speak to in the format host:instance
System.Boolean	Wait	If True, this function will not return until speaking has finished. If False, the function returns immediately and the speaking is queued

View Source

PluginFunction(String, String, Object[])

Execute a specific function declared within a plugin installed on the HomeSeer system. This calls PluginFunction(String, Object[]) on the target plugin.

Declaration

C#
Visual Basic

object PluginFunction(string pluginId, string procName, object[] params)

Parameters

Type	Name	Description
System.String	pluginId	The Id of the plugin that owns the function
System.String	procName	The name of the function
System.Object[]	params	An array of parameters to pass to the function being called

Returns

Type	Description
System.Object	An object that contains the return value from the function called. You are on your own when it comes to casting this to the right type.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when either the `pluginId` or `procName` parameters are null or whitespace
System.Collections.Generic.KeyNotFoundException	Thrown when a plugin with the specified ID is not found in the list of installed plugins
System.AggregateException	Thrown when there was an error trying to execute the function. Check the enclosed exception for details.

View Source

PluginPropertyGet(String, String)

Get a specific property declared within a plugin installed on the HomeSeer system. This calls PluginPropertyGet(String) on the target plugin.

Declaration

C#
Visual Basic

object PluginPropertyGet(string plugId, string propName)

Parameters

Type	Name	Description
System.String	plugId	The Id of the plugin that owns the property
System.String	propName	The exact name of the property

Returns

Type	Description
System.Object	An object representing the value of the target property

View Source

PluginPropertySet(String, String, Object)

Set a specific property declared within a plugin installed on the HomeSeer system. This calls PluginPropertySet(String, Object) on the target plugin

Declaration

C#
Visual Basic

void PluginPropertySet(string plugId, string propName, object propValue)

Parameters

Type	Name	Description
System.String	plugId	The Id of the plugin that owns the property
System.String	propName	The exact name of the property
System.Object	propValue	The value of the property to set. Its type must exactly match the type defined in the plugin.

View Source

RaiseGenericEventCB(String, Object[], String)

When an application or plug-in registers to receive specific types of generic HSEvent callbacks, this procedure is used to raise those callbacks and send information to that application. See RegisterGenericEventCB , UnRegisterGenericEventCB ,and HSEvent information for more details.

Declaration

C#
Visual Basic

void RaiseGenericEventCB(string genericType, object[] parms, string pluginId)

Parameters

Type	Name	Description
System.String	genericType	This is the generic type name that was used when the receiving plug-in or application called RegisterGenericEventCB. If you know that the plug-in or application that you wish to raise the generic event with used an asterisk as the Generic Type, then you can use any text here as that plug-in will receive all generic event callbacks.
System.Object[]	parms	These are parameters that you wish to be passed to the receiving application. As an array of objects, it can contain strings, integers, other objects, etc.
System.String	pluginId	The ID of the plugin

Remarks

View Source

RegisterDeviceIncPage(String, String, String)

There can only be one device inclusion process for each plugin. The page that is tagged as the device inclusion process will be displayed first in the list of features for the plugin and be shown in the list of devices users can add.

Declaration

C#
Visual Basic

void RegisterDeviceIncPage(string pluginId, string pageFilename, string linkText)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin
System.String	pageFilename	The filename of the page, ending with .html
System.String	linkText	The text that appears in the navigation menu

View Source

RegisterEventCB(Constants.HSEvent, String)

Call this function when your plugin initializes to notify HomeSeer that you want to be called when a specific event happens. The normal use for this is to be notified when a device changes value or it's displayed string changes. You will be notified about any device change, not just changes to your own devices. However, if your device is controlled and your SetIOMulti() call is made, after you call back with hs.SetDeviceValueByRef you will get an HSEvent notifying you about the value change. Since the change is to your device, this notification should be ignored. When an event is detected that has beenn registered by your plug-in, call is made to the HSEvent function in your plug-in. You can then handle the event. See HSEvent for more information and an example.

Declaration

C#
Visual Basic

void RegisterEventCB(Constants.HSEvent evType, string pluginId)

Parameters

Type	Name	Description
Constants.HSEvent	evType	The type of event to register a callback for
System.String	pluginId	The ID of the plugin that should be called

Remarks

View Source

RegisterFeaturePage(String, String, String)

The PluginFilename must end with .html and not include the enclosing folder name. The page must exist in the HomeSeer html folder as: PluginID/PluginFilename

Declaration

C#
Visual Basic

void RegisterFeaturePage(string pluginId, string pageFilename, string linkText)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin
System.String	pageFilename	The filename of the page, ending with .html
System.String	linkText	The text that appears in the navigation menu

View Source

RegisterGenericEventCB(String, String)

HomeSeer has the ability to raise events in applications and plug-ins when one of a list of specific events in HomeSeer occurs (See RegisterEventCB). RegisterGenericEventCB allows an application or plug-in writer the opportunity to have custom events raised and to enable other applications and plug-ins to receive those callbacks. To remove the callback script, call UnRegisterGenericEventCB.

Declaration

C#
Visual Basic

void RegisterGenericEventCB(string genericType, string pluginId)

Parameters

Type	Name	Description
System.String	genericType	This is a string that identifies the callback. For example, a type of "MyPlugEvent" would mean that calls to RaiseGenericEventCB using something other than "MyPlugEvent" would be ignored. This string should be unique, and should be provided to all applications wishing to register to receive these callbacks. A special value of a single asterisk (*) can be used to indicate that you wish to receive ALL generic type callbacks from other plug-ins/applications.
System.String	pluginId	The ID of the plugin to call

Remarks

View Source

RegisterPlugin(String, String)

This will add the specified ID/filename pair to HomeSeer's list of plugins to check when it runs through the plugin initialization process.

Declaration

C#
Visual Basic

bool RegisterPlugin(string pluginId, string pluginName)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin to register
System.String	pluginName	The name of the plugin to register

Returns

Type	Description
System.Boolean	TRUE if the plugin was registered successfully; FALSE if there was a problem with registration

View Source

RegisterProxySpeakPlug(String)

After this registration, whenever a Speak command is issued in HomeSeer, your plug-in's SpeakIn procedure will be called instead. When your plug-in wishes to have HomeSeer actually speak something, it uses SpeakProxy instead of Speak.

If you no longer wish to proxy Speak commands in your plug-in, or when your plug-in has its Shutdown procedure called, use UnRegisterProxySpeakPlug to remove the registration as a speak proxy.

Declaration

C#
Visual Basic

void RegisterProxySpeakPlug(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The Id of your plugin

View Source

RemoveRefFromCategory(String, Int32)

Remove a ref from a category

Declaration

C#
Visual Basic

List<int> RemoveRefFromCategory(string id, int devRef)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.Int32	devRef	The ref to remove from the category

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	The current list of refs on the category after removing the one specified

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

RemoveRefsFromCategory(String, List<Int32>)

Remove a list of refs from a category

Declaration

C#
Visual Basic

List<int> RemoveRefsFromCategory(string id, List<int> devRefs)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.Collections.Generic.List<System.Int32>	devRefs	The refs to remove from the category

Returns

Type	Description
System.Collections.Generic.List<System.Int32>	The current list of refs on the category after removing the ones specified

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

ReplaceVariables(String)

HomeSeer supports the use of replacement variables, which is the use of special tags to indicate where HomeSeer should replace the tag with text information. A full list of replacement variables is listed in HomeSeer's help file.

Declaration

C#
Visual Basic

string ReplaceVariables(string strIn)

Parameters

Type	Name	Description
System.String	strIn	A string with the replacement variables

Returns

Type	Description
System.String	A string with the replacement variables removed with the indicated values put in their place

View Source

RestartSystem()

Shutdown and restart the HS system. This restarts the hardware

Declaration

C#
Visual Basic

void RestartSystem()

View Source

RunScript(String, Boolean, Boolean)

Run a script file

Declaration

C#
Visual Basic

object RunScript(string scr, bool Wait, bool SingleInstance)

Parameters

Type	Name	Description
System.String	scr	Filename of the script to run. Script must be located in the scripts folder.
System.Boolean	Wait	If True, function does not return until script finishes, if false, the script is run in the background.
System.Boolean	SingleInstance	If true, the script will not run if it is already running. If false, multiple copies of the same script can run.

Returns

Type	Description
System.Object

View Source

RunScriptFunc(String, String, Object, Boolean, Boolean)

Run a script file calling the given function in the file

Declaration

C#
Visual Basic

object RunScriptFunc(string scr, string func, object param, bool Wait, bool SingleInstance)

Parameters

Type	Name	Description
System.String	scr	Filename of the script to run. Script must be located in the scripts folder.
System.String	func	The name of the function to run. Normally the function "Main" is run if no function is specified.
System.Object	param	The parameter(s) to be passed to the function. This is an object and can be a single parameter such as a string, or multiple parameters in an array
System.Boolean	Wait	If True, function does not return until script finishes, if false, the script is run in the background.
System.Boolean	SingleInstance	If true, the script will not run if it is already running. If false, multiple copies of the same script can run.

Returns

Type	Description
System.Object

View Source

SaveImageFile(Byte[], String, Boolean)

Save the specified image, as a byte array, to file in the HomeSeer html images directory

Declaration

C#
Visual Basic

bool SaveImageFile(byte[] imageBytes, string destinationFile, bool overwriteExistingFile)

Parameters

Type	Name	Description
System.Byte[]	imageBytes	A byte array of the image to save
System.String	destinationFile	The path of the image following "\html\images"
System.Boolean	overwriteExistingFile	TRUE to overwrite any existing file, FALSE to not

Returns

Type	Description
System.Boolean	TRUE if the file was saved successfully, FALSE if there was a problem

Examples

The following example shows how to download an image from a URL and save the bytes to file from the HSPI class.

var url = "http://homeseer.com/images/HS4/hs4-64.png";
var webClient = new WebClient();
var imageBytes = webClient.DownloadData(url);
var filePath = $"{Id}\\{Path.GetFileName(url)}";
if (!HomeSeerSystem.SaveImageFile(imageBytes, filePath, true)) {
    Console.WriteLine($"Error saving {url} to {filePath}");
}

The following example shows how to convert an image to bytes and save them from the HSPI class.

var myImage = System.Drawing.Image.FromFile("sampleImage.png");
var imageBytes = new byte[0];
using (var ms = new MemoryStream()) {
    myImage.Save(ms, myImage.RawFormat);
    imageBytes = ms.toArray();
}
var filePath = $"{Id}\\sampleImage.png";
if (!HomeSeerSystem.SaveImageFile(imageBytes, filePath, true)) {
    Console.WriteLine($"Error saving sampleImage.png to {filePath}");
}

SaveINISetting(String, String, String, String)

Save the new value of a setting

Declaration

C#
Visual Basic

void SaveINISetting(string sectionName, string key, string value, string fileName)

Parameters

Type	Name	Description
System.String	sectionName	The name of the section the setting is saved to
System.String	key	The key of the setting
System.String	value	The value to save
System.String	fileName	The name of the INI file to save the setting to

View Source

SaveVar(String, Object)

Save the global variable contained in the obj parameter. The parameter may be any variable type such as a string or integer, or it may be a reference to an object created with CreateObject

Declaration

C#
Visual Basic

string SaveVar(string name, object obj)

Parameters

Type	Name	Description
System.String	name	The name of the global variable
System.Object	obj	The object to be saved

Returns

Type	Description
System.String	An empty string no error occured, or an error string if one did occur.

View Source

SendControlForFeatureByString(Int32, Double, String)

Send a control request through HomeSeer to the SetIOMulti(List<ControlEvent>) implementation for the Interface that owns the device. This is different than SendControlForFeatureByValue(Int32, Double) because the value that describes the desired control outcome is encoded into a string and cannot be described by a double.

If you own the device being controlled, you should be calling UpdateFeatureValueByRef(Int32, Double), UpdateFeatureValueStringByRef(Int32, String), or UpdatePropertyByRef(Int32, EProperty, Object) respectively.

Declaration

C#
Visual Basic

bool SendControlForFeatureByString(int devOrFeatRef, double controlValue, string controlString)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the device or feature to control. You should only be pointing at HsDevice instead of its HsFeature for legacy devices.
System.Double	controlValue	The value corresponding with the TargetValue or TargetRange of the StatusControl to select and include in the ControlEvent being sent to the owning plugin.
System.String	controlString	The desired value to send to the control for processing. This is passed to ControlString

Returns

Type	Description
System.Boolean	True if the control event succeeded, False if an error was reported

Remarks

This is the same as the legacy method CAPIControlHandler(CAPIControl)

Most simple features use a single value within a range of decimal numbers to control their state. These situations can easily be hardcoded as StatusControls allowing HomeSeer to automatically handle processing control requests tied to these values. IE A dimmable light uses a value of 0-100 to determine what state it is in. This usually requires 3 StatusControls: one for off (0), one for a variable on state (1-99), and one for full brightness (100) This does not work well for values that cannot be described by a range of decimal numbers or require more than a handful of StatusControls. When a more complex data value is required to describe the desired state to set the feature to, a string is used. IE the color of a light uses a value from 0-16777216. That requires 16777216 different StatusControls. It is more efficient to send the raw value to the handling plugin for processing.

View Source

SendControlForFeatureByValue(Int32, Double)

Send a control request through HomeSeer to the SetIOMulti(List<ControlEvent>) implementation for the Interface that owns the device.

Declaration

C#
Visual Basic

bool SendControlForFeatureByValue(int devOrFeatRef, double value)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the device or feature to control. You should only be pointing at HsDevice instead of its HsFeature for legacy devices.
System.Double	value	The value corresponding with the TargetValue or TargetRange to send a control event for

Returns

Type	Description
System.Boolean	True if the control event succeeded, False if an error was reported

Remarks

This is the same as the legacy method CAPIControlHandler(CAPIControl)

View Source

SendEmail(String, String, String, String, String, String, String)

Send an Email message

Declaration

C#
Visual Basic

void SendEmail(string to, string from, string cc, string bcc, string subject, string message, string attach)

Parameters

Type	Name	Description
System.String	to	The address you are sending the email to
System.String	from	The adress you are sending from. Note that some ISPs will not allow you to put just anything in this field. You may be required to put your real E-mail address here. If you are using MAPI to handle your E-mail, MAPI will enter your E-mail address that is associated with your default E-mail account. In that case, this field will be ignored.
System.String	cc	The CC address
System.String	bcc	The BCC address
System.String	subject	The subject of the email
System.String	message	The body of the email
System.String	attach	The abosulte path to the file to be attached to the email.

View Source

SetImageForCategoryById(String, String)

Set the image path for a category

Declaration

C#
Visual Basic

void SetImageForCategoryById(string id, string image)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.String	image	The path to the image for the category. Use /html/images/Categories/

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

SetNameForCategoryById(String, String)

Set the name for a category

Declaration

C#
Visual Basic

void SetNameForCategoryById(string id, string name)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.String	name	The new name for the category

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

SetRefsForCategoryById(String, List<Int32>)

Set the list of refs for a category

Declaration

C#
Visual Basic

void SetRefsForCategoryById(string id, List<int> devRefs)

Parameters

Type	Name	Description
System.String	id	The ID of the category
System.Collections.Generic.List<System.Int32>	devRefs	The new list of refs for the category

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	Thrown if a category with that ID isn't found

View Source

SetVolume(Int32, String)

Set the volume on a speaker client

Declaration

C#
Visual Basic

void SetVolume(int level, string Host)

Parameters

Type	Name	Description
System.Int32	level	Volume level in the range of 0-100
System.String	Host	The speaker host to speak to in the format host:instance

View Source

ShutDown()

Shutdown the HS system

Declaration

C#
Visual Basic

void ShutDown()

View Source

Speak(Int32, String, Boolean, String)

This function speaks some text

Declaration

C#
Visual Basic

void Speak(int speechDevice, string spokenText, bool wait, string host = "")

Parameters

Type	Name	Description
System.Int32	speechDevice	This is the device that is to be used for the speaking. In older versions of HomeSeer, this value was used to indicate the sound card to use, and if it was over 100, then it indicated that it was speaking for HomeSeer Phone (device - 100 = phone line), or the WAV audio device to use. Although this is still used for HomeSeer Phone, speaks for HomeSeer phone are never proxied and so values >= 100 should never been seen in the device parameter.
System.String	spokenText	This is the text to be spoken, or if it is a WAV file to be played, then the characters ":" will be found starting at position 2 of the string as playing a WAV file with the speak command in HomeSeer REQUIRES a fully qualified path and filename of the WAV file to play.
System.Boolean	wait	This parameter tells HomeSeer whether to continue processing commands immediately or to wait until the speak command is finished.
System.String	host	This is a list of host:instances to speak or play the WAV file on. An empty string or a single asterisk (*) indicates all connected speaker clients on all hosts.

Remarks

PLEASE NOTE: Code related to the Speech components in HomeSeer were ported from the HS3 plugin API and have not been fully tested to verify full functionality from the new SDK. The Speech API may undergo significant changes in the near future. Please use with caution.

View Source

SpeakProxy(Int32, String, Boolean, String)

This procedure is used to cause HomeSeer to speak something when a speak proxy is registered and active. Since speak commands when a speak proxy plug-in is registered are trapped and passed to the SpeakIn procedure of the speak proxy plug-in, this command is used when the speak proxy plug-in is ready to do the real speaking.

Declaration

C#
Visual Basic

void SpeakProxy(int speechDevice, string spokenText, bool wait, string host = "")

Parameters

Type	Name	Description
System.Int32	speechDevice	This is the device that is to be used for the speaking. In older versions of HomeSeer, this value was used to indicate the sound card to use, and if it was over 100, then it indicated that it was speaking for HomeSeer Phone (device - 100 = phone line), or the WAV audio device to use. Although this is still used for HomeSeer Phone, speaks for HomeSeer phone are never proxied and so values >= 100 should never been seen in the device parameter. Pass the device parameter unchanged to SpeakProxy.
System.String	spokenText	This is the text to be spoken, or if it is a WAV file to be played, then the characters ":" will be found starting at position 2 of the string as playing a WAV file with the speak command in HomeSeer REQUIRES a fully qualified path and filename of the WAV file to play.
System.Boolean	wait	This parameter tells HomeSeer whether to continue processing commands immediately or to wait until the speak command is finished - pass this parameter unchanged to SpeakProxy.
System.String	host	This is a list of host:instances to speak or play the WAV file on. An empty string or a single asterisk (*) indicates all connected speaker clients on all hosts. Normally this parameter is passed to SpeakProxy unchanged.

Remarks

View Source

SpeakToFile(String, String, String)

Sends TTS to a file using the system voice

Declaration

C#
Visual Basic

bool SpeakToFile(string Text, string Voice, string FileName)

Parameters

Type	Name	Description
System.String	Text	The text to speak
System.String	Voice	The voice to use, SAPI only on Windows
System.String	FileName	Filename to send the speech to

Returns

Type	Description
System.Boolean

Remarks

View Source

TriggerEventByRef(Int32)

Run an event causing it to execute its actions

Declaration

C#
Visual Basic

bool TriggerEventByRef(int eventRef)

Parameters

Type	Name	Description
System.Int32	eventRef	The Ref of the event

Returns

Type	Description
System.Boolean	TRUE if the event run started successfully. This does not indicate that the actions succeeded.

Remarks

View Source

TriggerFire(String, TrigActInfo)

This function is a callback function and is called when a plugin detects that a trigger condition is true.

Declaration

C#
Visual Basic

void TriggerFire(string pluginId, TrigActInfo trigInfo)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin If you are targeting a trigger owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `pluginId`
TrigActInfo	trigInfo	The data of the trigger to fire

Remarks

View Source

TriggerMatches(String, Int32, Int32)

This function returns an array of TrigActInfo which matches the given plug-in, trigger number, and sub-trigger number provided. GetTriggers returns all triggers, so use TriggerMatches when you only want to know if there are triggers in events for a specific plug-in's trigger.

Declaration

C#
Visual Basic

TrigActInfo[] TriggerMatches(string pluginId, int trigId, int subTrigId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin If you are targeting triggers owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `pluginId`
System.Int32	trigId	The ID of the trigger
System.Int32	subTrigId	The ID of the subtrigger

Returns

Type	Description
TrigActInfo[]	An array of TrigActInfo which matches the given plug-in, trigger number, and sub-trigger number provided

Remarks

View Source

UnregisterDeviceIncPage(String)

Unregister the device inclusion page for this plugin.

Declaration

C#
Visual Basic

void UnregisterDeviceIncPage(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin

View Source

UnregisterFeaturePage(String, String)

Unregister a feature page to remove any navigation links to the page.

Declaration

C#
Visual Basic

void UnregisterFeaturePage(string pluginId, string pageFilename)

Parameters

Type	Name	Description
System.String	pluginId	The ID of the plugin
System.String	pageFilename	The filename of the page, ending with .html. This must be exactly the same as the filename used to register the page

View Source

UnRegisterGenericEventCB(String, String)

This will remove an application or plug-in from the list that should receive generic event callbacks for the type indicated (See RegisterGenericEventCB).

Declaration

C#
Visual Basic

void UnRegisterGenericEventCB(string genericType, string pluginId)

Parameters

Type	Name	Description
System.String	genericType	This is the generic type string that was used to register the callback with RegisterGenericEventCB.
System.String	pluginId	The ID of the plugin remove from the callback listen

Remarks

View Source

UnRegisterProxySpeakPlug(String)

Unregister a plug-in as a Speak proxy that was previously registered using RegisterProxySpeakPlug.

Declaration

C#
Visual Basic

void UnRegisterProxySpeakPlug(string pluginId)

Parameters

Type	Name	Description
System.String	pluginId	The Id of your plugin

View Source

UpdateDeviceByRef(Int32, Dictionary<EProperty, Object>)

Update some properties on a device

The collection of changes passed as parameter is usually Changes

Declaration

C#
Visual Basic

HsDevice UpdateDeviceByRef(int devRef, Dictionary<EProperty, object> changes)

Parameters

Type	Name	Description
System.Int32	devRef	The Ref of the HsDevice to update
System.Collections.Generic.Dictionary<EProperty, System.Object>	changes	A collection of EProperty with their new values

Returns

Type	Description
HsDevice	The updated HsDevice

View Source

UpdateFeatureByRef(Int32, Dictionary<EProperty, Object>)

Update some properties on a feature

The collection of changes passed as parameter is usually Changes

Declaration

C#
Visual Basic

HsFeature UpdateFeatureByRef(int featRef, Dictionary<EProperty, object> changes)

Parameters

Type	Name	Description
System.Int32	featRef	The Ref of the HsFeature to update
System.Collections.Generic.Dictionary<EProperty, System.Object>	changes	A collection of EProperty with their new values

Returns

Type	Description
HsFeature	The updated HsFeature

Remarks

Do not use this method to update StatusControls or StatusGraphics. Instead, use AddStatusControlToFeature(Int32, StatusControl), DeleteStatusControlByValue(Int32, Double), ClearStatusControlsByRef(Int32), AddStatusGraphicToFeature(Int32, StatusGraphic), DeleteStatusGraphicByValue(Int32, Double), ClearStatusGraphicsByRef(Int32)

View Source

UpdateFeatureValueByRef(Int32, Double)

Set the value on a feature and trigger HomeSeer to process the update to update the status accordingly.

To update the value without triggering HomeSeer to process the update, call UpdatePropertyByRef(Int32, EProperty, Object)

This does not fire a control event to the owning Interface. Use SendControlForFeatureByValue(Int32, Double) to control a device you do not own.

Declaration

C#
Visual Basic

bool UpdateFeatureValueByRef(int featRef, double value)

Parameters

Type	Name	Description
System.Int32	featRef	The unique reference of the feature to control
System.Double	value	The new value to set on the feature

Returns

Type	Description
System.Boolean	TRUE if the control sent correctly, FALSE if there was a problem

Remarks

This is the same as the legacy method SetDeviceValueByRef(Integer, Double, True).

View Source

UpdateFeatureValueStringByRef(Int32, String)

Set the value on a feature by string and trigger HomeSeer to process the update to update the status accordingly

This does not fire a control event to the owning Interface. Use SendControlForFeatureByValue(Int32, Double) to control a device you do not own.

Declaration

C#
Visual Basic

bool UpdateFeatureValueStringByRef(int featRef, string value)

Parameters

Type	Name	Description
System.Int32	featRef	The unique reference of the feature to control
System.String	value	The new value to set on the feature

Returns

Type	Description
System.Boolean	TRUE if the control sent correctly, FALSE if there was a problem

Remarks

This is the same as the legacy method SetDeviceString(Integer, String, True)

View Source

UpdatePlugAction(String, Int32, TrigActInfo)

Update the data saved to an event action

Declaration

C#
Visual Basic

string UpdatePlugAction(string plugId, int evRef, TrigActInfo actInfo)

Parameters

Type	Name	Description
System.String	plugId	The ID of the plugin that owns the action If you are targeting an action owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `plugId`
System.Int32	evRef	The Ref of the event
TrigActInfo	actInfo	The data to save to the event action

Returns

Type	Description
System.String	A message describing the result. Empty if it was successful

Remarks

View Source

UpdatePlugTrigger(String, Int32, TrigActInfo)

Update an existing plugin trigger in an event

Declaration

C#
Visual Basic

string UpdatePlugTrigger(string plugId, int evRef, TrigActInfo trigInfo)

Parameters

Type	Name	Description
System.String	plugId	The ID of the plugin that owns the trigger If you are targeting a trigger owned by a legacy plugin, use the IPlugInAPI.Name of the plugin for `plugId`
System.Int32	evRef	Reference # of the event to modify
TrigActInfo	trigInfo	The TrigActInfo that is to replace the existing trigger. The UID in this structure must match the UID in the original trigger

Returns

Type	Description
System.String	Returns an empty string on success or an error message

View Source

UpdatePropertyByRef(Int32, EProperty, Object)

Update one property on a device or a feature

When used with Value, this is the same as the legacy method SetDeviceValueByRef(Integer, Double, False). This does not fire a control event to the owning Interface. Use SendControlForFeatureByValue(Int32, Double) to control a device you do not own.

Declaration

C#
Visual Basic

void UpdatePropertyByRef(int devOrFeatRef, EProperty property, object value)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the AbstractHsDevice to update
EProperty	property	The EProperty to update
System.Object	value	The new value for this property

Remarks

View Source

Version()

Get the current version of HomeSeer that is running

Declaration

C#
Visual Basic

string Version()

Returns

Type	Description
System.String	The version string for HomeSeer in the format of MAJOR.MINOR.PATCH.BUILD

View Source

WindowsLogoffSystem()

Logs off the active user and closes all processes running under the user

Declaration

C#
Visual Basic

void WindowsLogoffSystem()

View Source

WindowsRebootSystem()

Shut down HS and reboot the hardware system

Declaration

C#
Visual Basic

void WindowsRebootSystem()

View Source

WindowsShutdownSystem()

Shut down HS and shutdown the hardware system

Declaration

C#
Visual Basic

void WindowsShutdownSystem()

View Source

WriteLog(ELogType, String, String, String)

Write a message to the HomeSeer logs

Declaration

C#
Visual Basic

void WriteLog(ELogType logType, string message, string pluginName, string color = "")

Parameters

Type	Name	Description
ELogType	logType	The ELogType to write
System.String	message	The message to write to the log
System.String	pluginName	The name of your plugin, used to mark the source of the log message
System.String	color	The color code to use. NOTE: Legacy HS3 API implementation