Interface IPlugin

C#
Visual Basic

public interface IPlugin

Namespace: HomeSeer.PluginSdk

Assembly: PluginSdk.dll

The core plugin interface used by HomeSeer to interact with third-party plugins.

The AbstractPlugin class provides a default implementation of this interface that should be used to develop plugins.

Properties

View Source

AccessLevel

Return the access level of this plug-in. Access level is the licensing mode. Use the integer value corresponding to the EAccessLevel for your plugin

int AccessLevel { get; }

Property Value

Type	Description
System.Int32

View Source

ActionCount

The number of unique event actions the plugin supports

Declaration

C#
Visual Basic

int ActionCount { get; }

Property Value

Type	Description
System.Int32

View Source

HasSettings

Whether the plugin has settings pages or not.

If this is TRUE, you must return valid JUI data in GetJuiSettingsPages()

Declaration

C#
Visual Basic

bool HasSettings { get; }

Property Value

Type	Description
System.Boolean

View Source

Id

Unique ID for this plugin, needs to be unique for all plugins.

Do NOT use special characters or spaces in your plugin ID

Declaration

C#
Visual Basic

string Id { get; }

Property Value

Type	Description
System.String

Remarks

The ID is used throughout the HomeSeer platform to target this plugin specifically via URL or internal code. It is recommended to use the name of your plugin, removing special characters and spaces, as the ID to make it easy to match them with one-another.

View Source

Name

The name of the plugin

Do NOT use special characters in your plugin name with the exception of "-", ".", and " " (space).

This is used to identify your plug-in to HomeSeer and your users. Keep the name to 16 characters or less.

Declaration

C#
Visual Basic

string Name { get; }

Property Value

Type	Description
System.String

View Source

SupportsConfigDevice

Whether this plugin supports a device configuration page for devices created/managed by it

TRUE will cause HomeSeer to call GetJuiDeviceConfigPage() for devices this plugin manages. FALSE means HomeSeer will not call GetJuiDeviceConfigPage() for any devices

Declaration

C#
Visual Basic

bool SupportsConfigDevice { get; }

Property Value

Type	Description
System.Boolean

View Source

SupportsConfigDeviceAll

Whether this plugin supports a device configuration page for all devices

TRUE will cause HomeSeer to call GetJuiDeviceConfigPage() for every device. FALSE means HomeSeer will not call GetJuiDeviceConfigPage() for all devices

Declaration

C#
Visual Basic

bool SupportsConfigDeviceAll { get; }

Property Value

Type	Description
System.Boolean

View Source

SupportsConfigFeature

Whether this plugin supports a feature configuration page for features created/managed by it

TRUE will cause HomeSeer to call GetJuiDeviceConfigPage() for features this plugin manages. FALSE means HomeSeer will not call GetJuiDeviceConfigPage() for any features

Declaration

C#
Visual Basic

bool SupportsConfigFeature { get; }

Property Value

Type	Description
System.Boolean

Remarks

Setting this to TRUE allows you to display a unique page for each feature instead of using a single page for the device and all of its features.

View Source

TriggerCount

The number of unique event triggers the plugin supports

Declaration

C#
Visual Basic

int TriggerCount { get; }

Property Value

Type	Description
System.Int32

Methods

View Source

ActionBuildUI(TrigActInfo)

Called by the HomeSeer system when an event is in edit mode and in need of HTML controls for the user.

Declaration

C#
Visual Basic

string ActionBuildUI(TrigActInfo actInfo)

Parameters

Type	Name	Description
TrigActInfo	actInfo	Object that contains information about the action like current selections.

Returns

Type	Description
System.String	HTML controls that need to be displayed so the user can select the action parameters.

View Source

ActionConfigured(TrigActInfo)

Called by the HomeSeer system to verify that the configuration is valid and can be saved

Declaration

C#
Visual Basic

bool ActionConfigured(TrigActInfo actInfo)

Parameters

Type	Name	Description
TrigActInfo	actInfo	Object describing the action.

Returns

Type	Description
System.Boolean	TRUE if the given action is configured properly; FALSE if the action shouldn't be saved

View Source

ActionFormatUI(TrigActInfo)

Called by the HomeSeer system when an event action is finished being configured and needs to be displayed in an easy to read format.

Declaration

C#
Visual Basic

string ActionFormatUI(TrigActInfo actInfo)

Parameters

Type	Name	Description
TrigActInfo	actInfo	Object that contains information about the current configuration of the trigger.

Returns

Type	Description
System.String	HTML representing easy to read text describing the action

View Source

ActionProcessPostUI(Dictionary<String, String>, TrigActInfo)

Called by the HomeSeer system to process selections when a user edits your event actions.

Declaration

C#
Visual Basic

EventUpdateReturnData ActionProcessPostUI(Dictionary<string, string> postData, TrigActInfo trigInfoIn)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.String, System.String>	postData	A collection of name value pairs that include the user's selections.
TrigActInfo	trigInfoIn	Object that contains information about the action.

Returns

Type	Description
EventUpdateReturnData	Object the holds the parsed information for the action. HomeSeer will save this information for you in the database.

View Source

ActionReferencesDevice(TrigActInfo, Int32)

Called by the HomeSeer system to determine if a specified device is referenced by a certain action.

Declaration

C#
Visual Basic

bool ActionReferencesDevice(TrigActInfo actInfo, int devRef)

Parameters

Type	Name	Description
TrigActInfo	actInfo	Object describing the action.
System.Int32	devRef	The reference ID of the device to check

Returns

Type	Description
System.Boolean	TRUE if the action references the device; FALSE if it does not

View Source

GetActionNameByNumber(Int32)

Return the name of the action given an action number

The name of the action will be displayed in the HomeSeer events actions list.

Declaration

C#
Visual Basic

string GetActionNameByNumber(int actionNum)

Parameters

Type	Name	Description
System.Int32	actionNum	The number of the action to get the name for

Returns

Type	Description
System.String	The name of the action associated with the action number

View Source

GetJuiDeviceConfigPage(Int32)

Called by the HomeSeer software to obtain a HS-JUI device or feature configuration page for a specific device or feature

Declaration

C#
Visual Basic

string GetJuiDeviceConfigPage(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The device or feature reference to get the page for

Returns

Type	Description
System.String	A JSON serialized Jui.Page

View Source

GetJuiSettingsPages()

Called by the HomeSeer software to obtain a list of settings pages

Declaration

C#
Visual Basic

string GetJuiSettingsPages()

Returns

Type	Description
System.String	A SettingsCollection serialized to a JSON string

View Source

GetSubTriggerCount(Int32)

Returns the number of sub triggers the plugin supports for the specified trigger number

Declaration

C#
Visual Basic

int GetSubTriggerCount(int triggerNum)

Parameters

Type	Name	Description
System.Int32	triggerNum	The number of the trigger to check

Returns

Type	Description
System.Int32	The number of sub triggers the specified trigger number supports

View Source

GetSubTriggerNameByNumber(Int32, Int32)

The name of the sub trigger with the specified number of the trigger with the specified number

Declaration

C#
Visual Basic

string GetSubTriggerNameByNumber(int triggerNum, int subTriggerNum)

Parameters

Type	Name	Description
System.Int32	triggerNum	The number of the trigger to check
System.Int32	subTriggerNum	The number of the sub trigger to check

Returns

Type	Description
System.String	The name of the sub trigger

View Source

GetTriggerNameByNumber(Int32)

Return the name of the given trigger based on the specified trigger number

Declaration

C#
Visual Basic

string GetTriggerNameByNumber(int triggerNum)

Parameters

Type	Name	Description
System.Int32	triggerNum	The trigger number to get the name for

Returns

Type	Description
System.String	The name of the trigger

View Source

HandleAction(TrigActInfo)

Called by the HomeSeer system when an event is triggered and the plugin needs to carry out a specific action.

Declaration

C#
Visual Basic

bool HandleAction(TrigActInfo actInfo)

Parameters

Type	Name	Description
TrigActInfo	actInfo	Object describing the trigger and action.

Returns

Type	Description
System.Boolean	TRUE if the action was executed successfully; FALSE if there was an error

View Source

HasJuiDeviceConfigPage(Int32)

Called by HomeSeer Core to determine if a device or feature configuration page is available for a particular device or feature. Only called if SupportsConfigDevice or SupportsConfigFeature or SupportsConfigDeviceAll is set to TRUE.

Declaration

C#
Visual Basic

bool HasJuiDeviceConfigPage(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The Ref of the device

Returns

Type	Description
System.Boolean	True if there is a page available, false if not. Returning True will cause HomeSeer Core to call GetJuiDeviceConfigPage(Int32) for the device or feature

View Source

HsEvent(Constants.HSEvent, Object[])

When you wish to have HomeSeer call back in to your plug-in or application when certain events happen in the system, call the RegisterEventCB procedure and provide it with event you wish to monitor.
See RegisterEventCB for more information and an example and event types.

The parameters are passed in an array of objects. Each entry in the array is a parameter. The number of entries depends on the type of event and are described below. The event type is always present in the first entry or params(0).

Declaration

C#
Visual Basic

void HsEvent(Constants.HSEvent eventType, object[] params)

Parameters

Type	Name	Description
Constants.HSEvent	eventType	The type of event that has occurred
System.Object[]	params	The data associated with the event

View Source

InitIO()

Called by the HomeSeer system to initialize the plugin.

This is the primary entry point for all plugins. Start the plugin and get it ready for use.

Declaration

C#
Visual Basic

bool InitIO()

Returns

Type	Description
System.Boolean	TRUE if the plugin started successfully; FALSE if it did not You should opt for throwing an exception that contains a detailed messaged over returning FALSE whenever possible.

View Source

IsTriggerConfigValid(TrigActInfo)

Given a TrigActInfo object, detect if this trigger is configured properly

Declaration

C#
Visual Basic

bool IsTriggerConfigValid(TrigActInfo trigInfo)

Parameters

Type	Name	Description
TrigActInfo	trigInfo	The trigger info to validate

Returns

Type	Description
System.Boolean	TRUE if the trigger is configured properly, FALSE otherwise

View Source

OnStatusCheck()

Called by the HomeSeer system to determine the status of the plugin.

Declaration

C#
Visual Basic

PluginStatus OnStatusCheck()

Returns

Type	Description
PluginStatus	A PluginStatus object describing the state of the plugin

PluginFunction(String, Object[])

Called by the HomeSeer system to run a plugin function by name using reflection

Declaration

C#
Visual Basic

object PluginFunction(string procName, object[] params)

Parameters

Type	Name	Description
System.String	procName	The name of the method to execute
System.Object[]	params	The parameters to execute the method with

Returns

Type	Description
System.Object	The result of the method execution

View Source

PluginPropertyGet(String)

Called by the HomeSeer system to get the value of a property by name using reflection

Declaration

C#
Visual Basic

object PluginPropertyGet(string propName)

Parameters

Type	Name	Description
System.String	propName	The name of the property

Returns

Type	Description
System.Object	The value of the property

View Source

PluginPropertySet(String, Object)

Called by the HomeSeer system to set the value of a property by name using reflection

Declaration

C#
Visual Basic

void PluginPropertySet(string propName, object value)

Parameters

Type	Name	Description
System.String	propName	The name of the property
System.Object	value	The new value of the property

View Source

PostBackProc(String, String, String, Int32)

Called by the HomeSeer system when a page owned by this plugin receives an HTTP POST request

Declaration

C#
Visual Basic

string PostBackProc(string page, string data, string user, int userRights)

Parameters

Type	Name	Description
System.String	page	The page that received the POST request
System.String	data	The data included in the request
System.String	user	The user responsible for initiating the request
System.Int32	userRights	The user's rights

Returns

Type	Description
System.String	A string of data that is returned to the requester

View Source

SaveJuiDeviceConfigPage(String, Int32)

Save updated values for a HS-JUI formatted device or feature config page

Declaration

C#
Visual Basic

bool SaveJuiDeviceConfigPage(string pageContent, int devOrFeatRef)

Parameters

Type	Name	Description
System.String	pageContent	A JSON serialized Jui.Page describing what has changed about the page
System.Int32	devOrFeatRef	The reference of the device or feature the config page is for

Returns

Type	Description
System.Boolean	TRUE if the save was successful; FALSE if it was unsuccessful. An exception should be thrown with details about the error if it was unsuccessful

View Source

SaveJuiSettingsPages(String)

Called by the HomeSeer system when settings changes need to be saved

Declaration

C#
Visual Basic

bool SaveJuiSettingsPages(string jsonString)

Parameters

Type	Name	Description
System.String	jsonString	A List of Jui.Pages containing views that have changed, serialized as JSON

Returns

Type	Description
System.Boolean	TRUE if the save was successful; FALSE if it was unsuccessful. An exception should be thrown with details about the error if it was unsuccessful

View Source

SetIOMulti(List<ControlEvent>)

Called by the HomeSeer system when a device that this plugin owns is controlled.

A plugin owns a device when its Interface property is set to the plugin ID.

Declaration

C#
Visual Basic

void SetIOMulti(List<ControlEvent> controlEvents)

Parameters

Type	Name	Description
System.Collections.Generic.List<ControlEvent>	controlEvents	A collection of ControlEvent objects, one for each device being controlled

View Source

ShutdownIO()

Called by the HomeSeer system to shutdown the plugin and its operations

Declaration

C#
Visual Basic

void ShutdownIO()

View Source

SpeakIn(Int32, String, Boolean, String)

If your plug-in is registered as a Speak proxy plug-in, then when HomeSeer is asked to speak something. It will pass the speak information to your plug-in using this procedure. When your plug-in is ready to do the actual speaking, it should call SpeakProxy, and pass the information that it got from this procedure to SpeakProxy. It may be necessary or a feature of your plug-in to modify the text being spoken or the host/instance list provided in the host parameter - this is acceptable.

Declaration

C#
Visual Basic

void SpeakIn(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

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

TriggerBuildUI(TrigActInfo)

Called by the HomeSeer system when an event is in edit mode and in need of HTML controls for the user.

Declaration

C#
Visual Basic

string TriggerBuildUI(TrigActInfo trigInfo)

Parameters

Type	Name	Description
TrigActInfo	trigInfo	Object that contains information about the current configuration of the trigger.

Returns

Type	Description
System.String	HTML controls that need to be displayed so the user can select the trigger parameters.

View Source

TriggerCanBeCondition(Int32)

Called by HomeSeer to determine if a given trigger can also be used as a condition

Declaration

C#
Visual Basic

bool TriggerCanBeCondition(int triggerNum)

Parameters

Type	Name	Description
System.Int32	triggerNum	The number of the trigger to check

Returns

Type	Description
System.Boolean	TRUE if the given trigger can also be used as a condition, for the given trigger number.

View Source

TriggerFormatUI(TrigActInfo)

Called by the HomeSeer system when an event trigger is finished being configured and needs to be displayed in an easy to read format.

Declaration

C#
Visual Basic

string TriggerFormatUI(TrigActInfo trigInfo)

Parameters

Type	Name	Description
TrigActInfo	trigInfo	Object that contains information about the current configuration of the trigger.

Returns

Type	Description
System.String	HTML representing easy to read text describing the trigger

View Source

TriggerProcessPostUI(Dictionary<String, String>, TrigActInfo)

Called by the HomeSeer system to process selections when a user edits your event triggers.

Declaration

C#
Visual Basic

EventUpdateReturnData TriggerProcessPostUI(Dictionary<string, string> postData, TrigActInfo trigInfoIn)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.String, System.String>	postData	A collection of name value pairs that include the user's selections.
TrigActInfo	trigInfoIn	Object that contains information about the trigger.

Returns

Type	Description
EventUpdateReturnData	Object the holds the parsed information for the trigger. HomeSeer will save this information for you in the database.

View Source

TriggerReferencesDeviceOrFeature(TrigActInfo, Int32)

Called by the HomeSeer system to determine if a specified device is referenced by a certain trigger.

Declaration

C#
Visual Basic

bool TriggerReferencesDeviceOrFeature(TrigActInfo trigInfo, int devOrFeatRef)

Parameters

Type	Name	Description
TrigActInfo	trigInfo	Object describing the trigger.
System.Int32	devOrFeatRef	The reference ID of the device or feature to check

Returns

Type	Description
System.Boolean	TRUE if the trigger references the device; FALSE if it does not

View Source

TriggerTrue(TrigActInfo, Boolean)

Called by HomeSeer when a trigger needs to be evaluated as a condition

Declaration

C#
Visual Basic

bool TriggerTrue(TrigActInfo trigInfo, bool isCondition = false)

Parameters

Type	Name	Description
TrigActInfo	trigInfo	Object describing the trigger
System.Boolean	isCondition	TRUE if the trigger represents a condition, FALSE if it is a trigger

Returns

Type	Description
System.Boolean	TRUE if the conditions are met; FALSE if they are not

View Source

UpdateStatusNow(Int32)

Called by the HomeSeer system when it needs the current status for a device/feature owned by the plugin.

This should force the device/feature to update its current status on HomeSeer.

Declaration

C#
Visual Basic

EPollResponse UpdateStatusNow(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The reference ID of the device/feature to poll

Returns

Type	Description
EPollResponse	An EPollResponse describing the result of the request