SearchAndSubscribe Method (StreamLayer)

In This Topic

Searches the table for existing rows using the query criteria and then subscribes to receive row events. This method must be called on the MCT. Use QueuedTask.Run.

Syntax

Visual Basic (Declaration)
C#

Public Function SearchAndSubscribe( _
   ByVal queryFilter As QueryFilter, _
   ByVal useRecyclingCursor As Boolean _
) As RealtimeCursor

public RealtimeCursor SearchAndSubscribe( 
   QueryFilter queryFilter,
   bool useRecyclingCursor
)

Parameters

queryFilter: A null query filter will search all rows and all rows that become available will be retrieved.
useRecyclingCursor: If set to true, all the entries in ArcGIS.Core.Data.Realtime.RealtimeCursor will reference the most current row returned by ArcGIS.Core.Data.Realtime.RealtimeCursor.Current. To ensure all the entries in ArcGIS.Core.Data.Realtime.RealtimeCursor remain unique, set useRecyclingCursor to false. The default is true.

Return Value

A ArcGIS.Core.Data.Realtime.RealtimeCursor that encapsulates the retrieved rows, as well as provides facilities to wait for new row events.

Exceptions

Exception	Description
ArcGIS.Core.CalledOnWrongThreadException	This method or property must be called within the lambda passed to QueuedTask.Run.
System.InvalidOperationException	Stream Layer was disconnected from its underlying feature class.
ArcGIS.Core.Data.Exceptions.GeodatabaseException	A geodatabase-related exception has occurred.

Remarks

This operation is atomic. It is guaranteed that the returned ArcGIS.Core.Data.Realtime.RealtimeCursor will correctly reflect any insert or delete operations that occured at any time during the exection of this method. Use ArcGIS.Core.Data.Realtime.RealtimeFeatureClass.SearchAndSubscribe to search and subscribe on any thread. If no query filter is set, all pre-existing rows will be searched and all rows that become available after subscribing will be retrieved.

Example

Search And Subscribe for Streaming Data

{
  // Note: call within QueuedTask.Run()
  {
    //query filter can be null to search and retrieve all rows
    //true means recycling cursor
    using (var rc = streamLayer.SearchAndSubscribe(qfilter, true))
    {
      //waiting for new features to be streamed
      //default is no cancellation
      while (rc.WaitForRowsAsync().Result)
      {
        while (rc.MoveNext())
        {
          using (var row = rc.Current)
          {
            //determine the origin of the row event
            switch (row.GetRowSource())
            {
              case RealtimeRowSource.PreExisting:
                //pre-existing row at the time of subscribe
                continue;
              case RealtimeRowSource.EventInsert:
                //row was inserted after subscribe
                continue;
              case RealtimeRowSource.EventDelete:
                //row was deleted after subscribe
                continue;
            }
          }
        }
      }
    }//row cursor is disposed. row cursor is unsubscribed

    //....or....
    //Use the feature class instead of the layer
    using var rfc = streamLayer.GetFeatureClass();
    //non-recycling cursor - 2nd param "false"
    using (RealtimeCursor rc = rfc.SearchAndSubscribe(qfilter, false))
    {
      //waiting for new features to be streamed
      //default is no cancellation
      while (rc.WaitForRowsAsync().Result)
      {
        //etc
      }
    }
  }
}

Search And Subscribe With Cancellation

{
  // Note: call within QueuedTask.Run()
  {
    //Recycling cursor - 2nd param "true"
    //or streamLayer.Subscribe(qfilter, true) to just subscribe
    using (var rc = streamLayer.SearchAndSubscribe(qfilter, true))
    {
      //auto-cancel after 20 seconds
      var cancel = new CancellationTokenSource(new TimeSpan(0, 0, 20));
      //catch TaskCanceledException
      try
      {
        while (rc.WaitForRowsAsync(cancel.Token).Result)
        {
          //check for row events
          while (rc.MoveNext())
          {
            using var row = rc.Current;
            //etc
          }
        }
      }
      catch (TaskCanceledException)
      {
        //Handle cancellation as needed
      }
      cancel.Dispose();
    }
  }
}

Explicitly Cancel WaitForRowsAsync

{
  RealtimeCursor rc = null;
  bool SomeConditionForCancel = false;

  //somewhere in our code we create a CancellationTokenSource
  var cancel = new CancellationTokenSource();
  //...

  //call cancel on the CancellationTokenSource anywhere in
  //the add-in, assuming the CancellationTokenSource is in scope
  if (SomeConditionForCancel)
    cancel.Cancel();//<-- will cancel the token

  //Within QueuedTask we are subscribed! streamLayer.Subscribe() or SearchAndSubscribe()
  try
  {
    //TaskCanceledException will be thrown when the token is cancelled
    while (rc.WaitForRowsAsync(cancel.Token).Result)
    {
      //check for row events
      while (rc.MoveNext())
      {
        using var row = rc.Current;
        //etc
      }
    }
  }
  catch (TaskCanceledException)
  {
    //Handle cancellation as needed
  }
  cancel.Dispose();
}

Requirements

Target Platforms: Windows 11 Home, Pro, Enterprise (64 bit)

ArcGIS Pro version: 3.0 or higher.

Reference

StreamLayer Class
StreamLayer Members

Send feedback