delphi10.2的解析单元Analytics.pas

这些函数用于记录应用程序活动事件。

type
  ///  <summary>由对象实现的接口，它管理用于记录应用程序活动事件的临时数据缓存。
  ///  </summary>
  IApplicationActivityCacheManager = interface
    ['{6145E812-8ECA-4B69-994C-26A81B2A84DC}']
    ///  <summary>返回临时数据缓存中的事件数量。</summary>
    function GetCacheCount: Integer;
    ///  <summary>持续收集到的数据, 可以上传至一个服务器或写入一个文件。
    ///  通常这个函数会生成一个背景线程来保存数据。
    ///  如果Wait是False, 则发送数据可以在后台完成。
    ///  如果Wait参数为True, 则所有的处理都应该在这个函数返回之前完成。</summary>
    procedure PersistData(const Wait: Boolean);
    ///  <summary>清空临时数据缓存。</summary>
    procedure ClearData;
    ///  <summary>将事件日志消息写到数据缓存中。</summary>
    procedure Log(const AMessage: string);
    ///  <summary>从临时数据缓存中删除一个事件。如果Index超出了范围，
    ///  ，则应该产生一个ERangeError异常。</summary>
    procedure RemoveEventAtIndex(const Index: Integer);
    ///  <summary>从临时事件缓存中检索指定索引中的事件。如果Index超出了范围，
    ///   则应该产生一个ERangeError异常。</summary>
    function GetEventAtIndex(const Index: Integer): string;
    ///  <summary>设置一个事件处理程序，当临时数据缓存达到其最大容量时，它就会被触发。
    ///  </summary>
    procedure SetOnDataCacheFull(const AValue: TNotifyEvent);
    ///  <summary>检索当临时数据缓存达到最大容量时触发的事件处理程序。
    ///  </summary>
    function GetOnDataCacheFull: TNotifyEvent;
    ///  <summary>设置临时数据缓存的最大尺寸。</summary>
    procedure SetMaxCacheSize(const AValue: Integer);
    ///  <summary>获取临时数据缓存的最大尺寸</summary>
    function GetMaxCacheSize: Integer;
    ///  <summary>返回临时数据缓存中的事件数量。</summary>
    property CacheCount: Integer read GetCacheCount;
    ///  <summary>设置或恢复临时数据缓存的最大尺寸。</summary>
    property MaxCacheSize: Integer read GetMaxCacheSize write SetMaxCacheSize;
    ///  <summary>从临时数据缓存中返回指定索引中的事件。</summary>
    property Event[const Index: Integer]: string read GetEventAtIndex;
    ///  <summary>当临时数据缓存达到最大容量时，
    ///  设置或恢复被触发的事件处理程序。</summary>
    property OnDataCacheFull: TNotifyEvent read GetOnDataCacheFull write SetOnDataCacheFull;
  end;

  ///  <summary>应该由缓存管理器实现的接口，
  ///  如果它支持接收和存储某些应用程序环境数据的能力。</summary>
  IAppAnalyticsStartupDataRecorder = interface
    ['{783ED8DB-86BC-41C7-BBD3-443C19468FF1}']
    ///  <summary>为高速缓存管理器提供系统数据的方法，系统数据是AppAnalytics服务的v2所需要的</summary>
    procedure AddEnvironmentField(const AKey, AValue: string);
  end;


  ///  <summary>由对象实现的接口，这个对象想要接收应用程序活动的通知。</summary>
  ///  <remarks>"Track" 方法在事件处理序列中被调用，
  /// 因此，重要的是，这些方法要快，不要执行过多的数据操作。
  ///  通常，这些事件应该简单地存储在临时缓存中。</remarks>
  IApplicationActivityListener = interface
    ['{A67DE237-F274-4028-AAC8-DA0BDA0D5D78}']
    ///  <summary>当一个TAppActivity.AppStart事件被记录后，调用。</summary>
    procedure TrackAppStart(const TimeStamp: TDateTime);
    ///  <summary>当一个TAppActivity.AppExit事件被记录后，调用。</summary>
    procedure TrackAppExit(const TimeStamp: TDateTime);
    ///  <summary>当一个TAppActivity.ControlFocused事件被记录后，调用。</summary>
    procedure TrackControlFocused(const TimeStamp: TDateTime; const Sender: TObject);
    ///  <summary>当一个TAppActivity.WindowActivated事件被记录后，调用。</summary>
    procedure TrackWindowActivated(const TimeStamp: TDateTime; const Sender: TObject);
    ///  <summary>当一个TAppActivity.Custom事件被记录后，调用。
    /// Context是一个可选的对象引用，它可以用来提供关于事件的附加上下文。</summary>
    procedure TrackEvent(const TimeStamp: TDateTime; const Sender, Context: TObject);
    ///  <summary>当一个TAppActivity.Exception事件被记录后，调用。</summary>
    procedure TrackException(const TimeStamp: TDateTime; const E: Exception);
  end;


  ///  <summary>可由IApplicationActivityListener记录的事件类型的枚举。</summary>
  TAppActivity = (AppStart, AppExit, ControlFocused, WindowActivated, Exception, Custom);
  ///  <summary>TAppActivity值得集合.
  /// 通常用于实现IApplicationActivityListener的对象，以指示它将要记录的事件的类型。</summary>
  TAppActivityOptions = set of TAppActivity;

  ///  <summary>用于记录应用程序活动，
  ///  并向一个或多个IApplicationActivityListener对象发送通知的对象。
  ///   这个管理器的实例可以由框架的应用程序对象持有。 </summary>
  TAnalyticsManager = class
  strict private
    FListeners: TList<IApplicationActivityListener>;
    function GetTrackingEnabled: Boolean;
  public
    ///  <summary>破坏这个对象并释放对所有已注册的
    /// IApplicationActivityListener对象的引用。</summary>
    destructor Destroy; override;
    ///  <summary>注册一个活动侦听器。 侦听器将立即开始接收应用程序活动通知。
    ///  该对象将保留对侦听器的引用。
    ///  如果监听器以前注册过，它将不会再次注册。</summary>
    procedure RegisterActivityListener(const AListener: IApplicationActivityListener);
    ///  <summary>注销一个活动侦听器。
    ///   该侦听器将立即停止接收应用程序活动通知，该对象将释放其对侦听器的引用。
    ///  如果指定的监听器以前没有注册过，则不会采取任何行动。</summary>
    procedure UnregisterActivityListener(const AListener: IApplicationActivityListener);
    ///  <summary>记录一个可跟踪的应用程序活动。所有注册的活动监听器将被通知。</summary>
    procedure RecordActivity(const Activity: TAppActivity); overload;
    ///  <summary>记录一个可跟踪的应用程序活动。所有注册的活动监听器将被通知。</summary>
    procedure RecordActivity(const Activity: TAppActivity; const Sender: TObject); overload;
    ///  <summary>记录一个可跟踪的应用程序活动。所有注册的活动监听器将被通知。</summary>
    procedure RecordActivity(const Activity: TAppActivity; const Sender: TObject; const Context: TObject); overload;
    ///  <summary>如果至少有一个侦听器已注册，则返回True。否则返回False。</summary>
    property TrackingEnabled: Boolean read GetTrackingEnabled;
  end;

  ///  <summary>一个异常类型，它表示应用程序活动跟踪组件的初始化失败。
  /// </summary>
  EAnalyticsInitializationFailed = class(Exception)
  end;