Echelon LNS - Manual (Page 84)

LNS Programmer's Guide 70
• Event handlers should not try to release any event object parameters, per
COM rules. LNS will handle this itself on return from the event handler.
If a client needs to make a copy of an object parameter, it must
AddRef()
the object to ensure it remains valid. For more information on this, see
Avoiding Memory Leaks with LNS on page 319.
• Where possible, event handlers should avoid making new calls into LNS
(especially modifying calls), except to extract information from any
passed-in object parameters. This should not cause direct problems, but
no further events will be processed until the event handler returns when
using direct callbacks. As an alternative, you can post a Windows
message to your main thread for further processing.
• Transactions within event handlers are treated the same as outside event
handlers. In particular, any operations performed within in an event
handler will become a part of the current transaction.
• Event handlers should not start or terminate any transactions, especially
when using direct callbacks, except for cancellation of explicit
transactions from within an OnNssIdleEvent event handler.
• Event handlers will be executed from one of several non-client threads
when using direct callbacks. You may need to keep this in mind for
thread safety, e.g. if your application makes use of thread local storage.
For more information on direct callbacks and LNS, see Multi-Threading
and LNS Applications on page 318.
• Applications should not subscribe to an event unless the application is
prepared to withdraw useful information from an event, as receiving but
not responding to events causes undesirable performance degradation.
This can also consume a large amount of network bandwidth, particularly
for Full client applications.
Exception Handling
As mentioned in the LNS Components section in Chapter 3 of this document, LNS
defines a set of exceptions that will be returned when an operation fails for any reason.
With the enhanced support for ATL in LNS Turbo Edition, there are now several ways to
handle runtime errors and warnings. Most applications have a try/catch clause (or some
similar construct) for general exceptions or COM errors, such as ‘out of memory’ or
‘access violation’.
Every property and method in LNS has at least two public interfaces: one that returns
an error code, and one that does not. For example, ILcaAppDevices.get_Item()
returns HRESULT error codes and does not throw exceptions for LNS-specific error
conditions, and ILcaAppDevices.GetItem() uses exceptions to notify the application
of error conditions. If the developer chooses the interface that does not return an error
code, then their catch clause will catch and handle the error. When using this type of
interface, both errors and update warnings will be thrown as COM exceptions.
If the developer chooses the interface that returns an error code, then the catch clause
will not be invoked upon an LNS error or warning for that invocation. Instead, the
returned exception will contain an error code, 0x8004yyyy, where yyyy represents an
LNS error code (i.e. 0x4269) or an LNS warning code (i.e. 0x0FBE). For a complete list of
the exceptions LNS may return, see the LNS Errors Online Reference section of the LNS
Object Server Reference.