/// <summary>
/// <para> Throws or returns new IXiEventListItems (not null, but possibly zero-lenghth). </para>
/// <para> eventList is not null </para>
/// <para>
/// This method is used to poll the endpoint for changes to a specific event list. Event messages are sent when
/// there has been a change to the specified event list. A new alarm or event that has been added to the list, a
/// change to an alarm already in the list, or the deletion of an alarm from the list constitutes a change to the
/// list.
/// </para>
/// <para>
/// Once an event has been reported from the list, it is automatically deleted from the list. Alarms are only
/// deleted from the list when they transition to inactive and acknowledged.
/// </para>
/// <para>
/// This method return a list of event messages to the client application via the EventMessagesCallback callback
/// method. The list consists of alarm/event messages for new alarms/events in the Event List, and alarm/event
/// messages that represent state changes to alarms that are already in the list, including alarm/event messages
/// that identify state changes that caused alarms to tbe deleted from the list.
/// </para>
/// <para>
/// Null is returned as a keep-alive message when there have been no new alarm/event messages since the last
/// poll.
/// </para>
/// <para>
/// In addition, a special event message is included as the first item in the list to indicate to the client
/// that one or more event message have been discarded due to queue size limitations. All fields of this message
/// are set to null with the exception of the following:
/// </para>
/// <para> OccurrenceTime = current time of the response </para>
/// <para> EventType = EventType.DiscardedMessage </para>
/// <para> TextMessage = the number of event/alarm messages discarded since the last poll response was returned. </para>
/// </summary>
/// <param name="eventList"> The event list to poll (reported). </param>
/// <param name="filterSet">
/// Optional set of filters to further refine the selection from the alarms and events in the
/// list. The event list itself is created using a filter.
/// </param>
public IXiEventListItem[] PollEventChanges(XiEventList eventList, FilterSet?filterSet)
{
if (eventList is null)
{
throw new ArgumentNullException(@"eventList");
}
if (_disposed)
{
throw new ObjectDisposedException("Cannot access a disposed XiContext.");
}
if (_pollEndpoint is null)
{
throw new Exception("No Poll Endpoint");
}
if (_pollEndpoint.Disposed)
{
throw new Exception("Poll Endpoint is Disposed.");
}
EventMessage[]? eventMessages = null;
if (XiEndpointRoot.CreateChannelIfNotCreated(_pollEndpoint))
{
try
{
eventMessages = _pollEndpoint.Proxy.PollEventChanges(ContextId,
eventList.ServerListId,
filterSet);
_pollEndpoint.LastCallUtc = DateTime.UtcNow;
}
catch (Exception ex)
{
ProcessRemoteMethodCallException(ex);
}
}
IXiEventListItem[]? newEventListItems = EventMessagesCallbackInternal(eventList, eventMessages);
if (newEventListItems is null)
{
throw new Exception("PollEventChanges() error.");
}
return(newEventListItems);
}
/// <summary>
/// <para> Invokes EventList.EventMessagesCallbackEvent, if new items count > 0. </para>
/// <para> No throws. If error, returns null. Otherwise new IXiEventListItems (not null, but possibly zero-lenghth). </para>
/// <para> This callback method is implemented by the client to receive alarms and events. </para>
/// <para>
/// Servers send event messages to the client via this interface. Event messages are sent when there has been a
/// change to the specified event list. A new alarm or event that has been added to the list, a change to an alarm
/// already in the list, or the deletion of an alarm from the list constitutes a change to the list.
/// </para>
/// <para>
/// Once an event has been reported from the list, it is automatically deleted from the list. Alarms are only
/// deleted from the list when they transition to inactive and acknowledged.
/// </para>
/// </summary>
/// <param name="eventList"> The client identifier of the list for which alarms/events are being reported. </param>
/// <param name="eventMessages"> The array of alarms/events are being reported. </param>
private IXiEventListItem[]? EventMessagesCallbackInternal(XiEventList eventList, EventMessage[]?eventMessages)
{
if (eventList is null || eventList.Disposed)
{
return(null);
}
try
{
List <IXiEventListItem> newEventListItems = eventList.EventMessagesCallback(eventMessages);
if (newEventListItems.Count > 0)
{
eventList.RaiseEventMessagesCallbackEvent(newEventListItems);
}
return(newEventListItems.ToArray());
}
catch
{
return(null);
}
}
