Echelon LNS Plug-in - Manual (Page 40)

with the (now terminated) plug-in will result in exceptions in the directors. The desired behavior
would be for the plug-in to become invisible (instead of exiting) when the user clicked the exit button
and to delay exiting until the last director released its reference to the plug-in.
The overlap can also be in the other direction. A plug-in might not be visible when the last director
releases its reference to it. Some plug-ins might be designed to always run in the background, without
a user-interface. Even plug-ins that normally run as visible might be invisible when the director
releases the reference. For example, the director might have started the plug-in to gather information
from it (such as its default window height) or to register it (by sending it an LcaCommandRegister
(50) command) and then released the reference without making the plug-in visible. In this case, there
is no way for the user to end the plug-in (other than killing the plug-in from the Windows task
manager). In this case, the desired behavior is for the plug-in to exit if it is invisible when the last
director releases its reference to the plug-in.
Both of these overlaps are handled in the same way. The plug-in server should keep track of how
many directors are using it. The plug-in server should not exit until the last director has released its
reference and either the user has asked the plug-in to exit or the plug-in is invisible (and thus not
available for the user to ask it to exit).
The LNS Plug-in Framework automatically handles this by maintaining a server-wide object use count
and server lock count in the PluginServerBase class. The server will automatically shut down when
the object count and lock count reach 0. Individual plug-in objects (derived from the
PluginObjectBase class) automatically manage their object use counts. They do this by incrementing
the server’s object count upon construction, and decrementing it upon deconstruction.
When a plug-in object implements a user interface by deriving a class from the PluginFormBase
class, the form itself will maintain a reference to the associated plug-in object when the form is
activated (for example, when the director sets the Visible property). When the user closes the form,
the reference to the plug-in object is released, allowing the server to shut down if all other references
have been released.
What Plug-ins Do When They Run in Standalone Mode
Plug-ins must provide an option to run in standalone mode. When they are started with a command
line option of /regplugin, such as MyPlugIn /regplugin, they must register themselves in the
Windows registry. The LNS Plug-in Framework automatically does this.
Plug-ins should also support a command line option of /deregplugin; if started with this option a
plug-in should remove its LNS plug-in data and automation server registration from the Windows
registry. This command line option is implemented in the framework.
If started without this option, a plug-in must, at a minimum, either automatically write its registration
data in the Windows registry or provide an option to allow the user to request registry data setup. The
framework provides a user interface for this case that allows registration or de-registration options.
The plug-in may also provide other portions of its normal functionality in standalone mode, but it is
not required to do so.
You can override the RunStandalone() method of the PluginServerBase class to provide standalone
mode functionality in framework-based plug-ins.
Responding to Property Reads and Writes
The LNS Plug-in API defines a set of properties that all plug-ins must implement. Directors write to
these properties to tell the plug-in how it should display itself (in the case of properties such as Left,
Top, Height, Width, and Visible) or how to interact with networks (in the case of properties such as
NetworkName and NetworkInterfaceName). Directors can also read from these properties (and
from an additional set of read-only properties, such as Version and ManufacturerID). You can add
custom properties to a plug-in, but your plug-in must operate correctly even if a director never sets or
gets any of these custom properties.