Echelon LNS Plug-in - Manual (Page 39)

How Directors Pass Object Names
The objectName parameter of the SendCommand() method specifies the location of the target object
in the LNS object hierarchy. The name includes any qualification required to find the appropriate
object in the hierarchy. The qualification is provided with a path name, where each element of the path
name consists of a string in the following format:
className:objectName
Multiple elements are separated by slashes, so the complete syntax is:
className:objectName[/className:objectName…]
The class name is optional if it is unambiguous. The class ID of the target object is passed as a
parameter in SendCommand, so the class name for the last object in the path (which is the target) is
always unambiguous. Network, System, Subsystem, and AppDevice names are also unambiguous.
Collection object names are not specified in the path name. Subsystem paths can be specified with a
shorthand syntax using periods to separate the system name and subsystem names.
For example, the following object name specifies an application device named “Motor Controller 5” in
the “Belt 2” subsystem of the “Assembly Line 1” subsystem in the “240 Main Street” network:
240 Main Street/240 Main Street.Assembly Line 1.Belt 2/Motor Controller 5
The same name, with all optional class names included, would be:
LcaNetwork:240 Main Street/LcaSystem:240 Main Street/LcaSubsystem:Assembly Line
1/LcaSubsystem:Belt 2/LcaAppDevice:Motor Controller 5
Appendix C, Standard Plug-in Classes, lists the addressing syntax and class ID of each object class.
Classes that appear in multiple places in the object hierarchy have more than one addressing syntax.
Optional class names are left off of the addressing syntax descriptions.
Object names that include an Interface object show <interface> as the first element of the path name.
This represents one of the four options for specifying an Interface object as shown for the
LcaInterface class.
How Plug-ins Let Directors Know About Errors
Plug-ins inform directors of errors by raising COM exceptions. If an error occurs during an operation,
a plug-in can raise one of the standard exceptions listed in Appendix D, Standard Plug-in Exceptions,
or it can raise a custom exception. Custom exception codes must be greater than or equal to
LcaErrRangeUserStart (22000).
How Plug-ins Know When To Exit
Because a plug-in can receive commands from both directors and users, the question of when to exit
may not be clear. From a director’s point of view, the life cycle of the plug-in is as described in How
Directors Launch and Manipulate Plug-ins earlier in this chapter. The plug-in comes into existence
when the director creates the plug-in by creating an instance of its class that implements the LNS
Plug-in API and ceases to exist when the director releases the reference to the class.
From the user’s point of view, the plug-in does not come into existence until it appears on the screen
(for example, not until the director sets the Visible property to True and the plug-in displays a visible
window). The user does not expect the plug-in to terminate until the user tells it to do so, for example
by clicking on an Exit button. This also means that the user has no concept of the life-cycle of
“helper” plug-ins that may run only in the background (for example, plug-ins that do all their work
without becoming visible).
These two perceived life-cycles can overlap. A user might want to close a plug-in while one or more
directors still have references to it. If the plug-in were to exit at this time, the directors would all now
have references to invalid objects. This means that all subsequent attempts by the directors to interact