Interface IItemEventListener
Used by Lightstreamer Kernel to receive the update events and any asynchronous severe error notification from the Data Adapter. The listener instance is supplied to the Data Adapter by Lightstreamer Kernel (through the Remote Server) through a SetListener call. Update events are specified through maps (i.e. IDictionary) that associate fields and values. Depending on the kind of subscription, the mapping for fields unchanged since the previous update can be omitted. Some alternative methods to supply update events are available, but they have been deprecated. Field values should be expressed as String; the use of byte arrays is also allowed, but it has been deprecated.
Namespace: Lightstreamer.Interfaces.Data
Assembly: DotNetStandardAdapter.dll
Syntax
public interface IItemEventListenerMethods
ClearSnapshot(String)
Called by a Data Adapter to signal to Lightstreamer Kernel that the current Snapshot of the Item has suddenly become empty. More precisely:
- for subscriptions in MERGE mode, the current state of the Item will be cleared, as though an update with all fields valued as null were issued;
- for subscriptions in COMMAND mode, the current state of the Item will be cleared, as though a DELETE event for each key were issued;
- for subscriptions in DISTINCT mode, a suitable notification that the Snapshot for the Item should be cleared will be sent to all the clients currently subscribed to the Item (clients based on some old client library versions may not be notified); at the same time, the current recent update history kept by the Server for the Item will be cleared and this will affect the Snapshot for new subscriptions;
- for subscriptions in RAW mode, there will be no effect.
Note that this is a real-time event, not a Snapshot event; hence, in order to issue this call, it is not needed that the Data Adapter has returned true to IsSnapshotAvailable for the specified Item; moreover, if invoked while the Snapshot is being supplied, the Kernel will infer that the Snapshot has been completed.
The Adapter should ensure that, after an unsubscribe call for the Item has returned, a possible pending ClearSnapshot call related with the previous subscription request is no longer issued. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Kernel. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.
Declaration
void ClearSnapshot(string itemName)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | itemName | The name of the Item whose Snapshot has become empty. |
EndOfSnapshot(String)
Called by a Data Adapter to signal to Lightstreamer Kernel that no more Item Event belonging to the Snapshot are expected for an Item. This call is optional, because the Snapshot completion can also be inferred from the isSnapshot flag in the update calls. However, this call allows Lightstreamer Kernel to be informed of the Snapshot completion before the arrival of the first non-snapshot event. Calling this function is recommended if the Item is to be subscribed in DISTINCT mode. In case the Data Adapter returned false to IsSnapshotAvailable for the same Item, this function should not be called.
The Remote Adapter should ensure that, after an Unsubscribe call for the Item has returned, a possible pending EndOfSnapshot call related with the previous subscription request is no longer issued. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Remote Server. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.
Declaration
void EndOfSnapshot(string itemName)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | itemName | The name of the Item whose snapshot has been completed. |
Failure(Exception)
Called by a Data Adapter to notify Lightstreamer Kernel of the occurrence of a severe problem that can compromise future operation of the Data Adapter.
Declaration
void Failure(Exception exception)Parameters
| Type | Name | Description |
|---|---|---|
| System.Exception | exception | Any Excetion object, with the description of the problem. |
Update(String, IIndexedItemEvent, Boolean)
Called by a Data Adapter to send an Item Event to Lightstreamer Kernel when the Item Event is implemented as an IIndexedItemEvent instance.
Declaration
[Obsolete("The method is deprecated. Use the IDictionary version to supply field values.")]
void Update(string itemName, IIndexedItemEvent itemEvent, bool isSnapshot)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | itemName | The name of the Item whose values are carried by the Item Event. |
| IIndexedItemEvent | itemEvent | An IIndexedItemEvent instance. |
| System.Boolean | isSnapshot | True if the Item Event carries the Item Snapshot. |
Remarks
The method is deprecated. Use the IDictionary version to supply field values.
Update(String, IItemEvent, Boolean)
Called by a Data Adapter to send an Item Event to Lightstreamer Kernel when the Item Event is implemented as an IItemEvent instance.
Declaration
[Obsolete("The method is deprecated. Use the IDictionary version to supply field values.")]
void Update(string itemName, IItemEvent itemEvent, bool isSnapshot)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | itemName | The name of the Item whose values are carried by the Item Event. |
| IItemEvent | itemEvent | An IItemEvent instance. |
| System.Boolean | isSnapshot | True if the Item Event carries the Item Snapshot. |
Remarks
The method is deprecated. Use the IDictionary version to supply field values.
Update(String, IDictionary, Boolean)
Called by a Data Adapter to send an Item Event to Lightstreamer Kernel when the Item Event is implemented as a IDictionary instance.
The Remote Adapter should ensure that, after an Unsubscribe call for the Item has returned, no more Update calls are issued, until requested by a new subscription for the same Item. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Remote Server. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.
Declaration
void Update(string itemName, IDictionary itemEvent, bool isSnapshot)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | itemName | The name of the Item whose values are carried by the Item Event. |
| System.Collections.IDictionary | itemEvent | A IDictionary instance, in which Field names are associated to Field values. A value should be expressed as a String; the use of a byte array, to supply a string encoded in the ISO-8859-1 (ISO-LATIN-1) character set, is also allowed, but it has been deprecated. A Field value can be null or missing if the Field is not to be reported in the event. |
| System.Boolean | isSnapshot | True if the Item Event carries the Item Snapshot. |