Echelon LNS User Manual

Page 83

LNS Programmer's Guide

an automated installation tool. You could also use it to provide feedback

to a user about the configuration state of devices or routers on your
network. For example, when building a connection, you might want to be

informed of devices that could not be updated. Or, upon receiving a

commission status change event with an “update failed” code, your
application could indicate this by drawing a red circle around the device’s

icon. Later, when the device is reattached to the network and the Object
Server refreshes the device’s network image, your application can remove

the red circle upon receiving a commissioning status change event with

an "update succeeded" code.

• Attach/detach events. The OnAttachment event is generated when the

attachment status of an

AppDevice

Router

changes. Once an

application device or router has been commissioned, it can be monitored
via periodic pinging to ensure it is attached. A change in the attachment

status results in this event being generated. Note that the

attachment/detachment events can also be used to monitor the presence
of other remote Full client applications on the network.

• Licensing events. You can use the OnLicenseEvent event to monitor

when the licensing status of the LNS Server changes. This event is
generated upon device crediting, device debiting, deficit credit usage, and

license expiration.

• Missed-event events. The OnMissedEvent event is generated for Full

client applications when one or more events were generated, but not

received by subscribers. For example, missed events could occur while

your application’s Network Service Device is being updated. This event
will contain information about how many events were missed and

whether the missed events are recoverable. You can use the
SetEventSyncMode method to determine whether missed events can be
recovered or not, and you can use the DoEventSync method to maintain

event synchronization in the case of missed events. Consult the LNS
Object Server Reference help file for more information on these methods.

When implementing an event handler for any of the LNS-generated events discussed in

this document, the developer should take into account the following guidelines:

• Each event handler must be implemented as an IDispatch() method

with a valid DISPID. The valid DISPIDs you can use with LNS are

included in the

ConstEventIds

constant. For a complete list, see the

help page for the

ConstEventIds

constant in the LNS Object Server

Reference help file. LNS does not query your event sink object for

DISPIDs by name. This is usually handled automatically by the

application framework (e.g. ATL, MFC, Visual Basic) you are using.

• When not using direct callbacks, your application must service its

Windows Message Queue in order to receive events. In addition to not

receiving events, your application will appear to leak memory while the
queue is not serviced. This is usually only a concern for console or

Windows service applications. For more information on direct callbacks,

see Multi-Threading and LNS Applications on page 318.

• Each event handler should process the event, and return quickly. New

events cannot be processed by a client until the current event handler

returns.