Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2024 Project CHIP Authors
       3              :  *    All rights reserved.
       4              :  *
       5              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6              :  *    you may not use this file except in compliance with the License.
       7              :  *    You may obtain a copy of the License at
       8              :  *
       9              :  *        http://www.apache.org/licenses/LICENSE-2.0
      10              :  *
      11              :  *    Unless required by applicable law or agreed to in writing, software
      12              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14              :  *    See the License for the specific language governing permissions and
      15              :  *    limitations under the License.
      16              :  */
      17              : #pragma once
      18              : 
      19              : #include <app/ConcreteEventPath.h>
      20              : #include <app/EventLoggingDelegate.h>
      21              : #include <app/EventLoggingTypes.h>
      22              : #include <app/MessageDef/EventDataIB.h>
      23              : #include <app/data-model/Encode.h>
      24              : #include <app/data-model/FabricScoped.h>
      25              : #include <lib/core/CHIPError.h>
      26              : #include <lib/core/DataModelTypes.h>
      27              : #include <lib/support/logging/CHIPLogging.h>
      28              : #include <system/SystemClock.h>
      29              : 
      30              : #include <optional>
      31              : 
      32              : namespace chip {
      33              : namespace app {
      34              : namespace DataModel {
      35              : 
      36              : class EventsGenerator;
      37              : 
      38              : namespace internal {
      39              : template <typename T>
      40              : class SimpleEventPayloadWriter : public EventLoggingDelegate
      41              : {
      42              : public:
      43           56 :     SimpleEventPayloadWriter(const T & aEventData) : mEventData(aEventData){};
      44           55 :     CHIP_ERROR WriteEvent(chip::TLV::TLVWriter & aWriter) final override
      45              :     {
      46           55 :         return DataModel::Encode(aWriter, TLV::ContextTag(EventDataIB::Tag::kData), mEventData);
      47              :     }
      48              : 
      49              : private:
      50              :     const T & mEventData;
      51              : };
      52              : 
      53              : std::optional<EventNumber> GenerateEvent(const EventOptions & eventOptions, EventsGenerator & generator,
      54              :                                          EventLoggingDelegate & delegate, bool isFabricSensitiveEvent);
      55              : 
      56              : } // namespace internal
      57              : 
      58              : /// Exposes event generation capabilities.
      59              : ///
      60              : /// Allows callers to "generate events" which effectively notifies of an event having
      61              : /// ocurred.
      62              : class EventsGenerator
      63              : {
      64              : public:
      65         1001 :     virtual ~EventsGenerator() = default;
      66              : 
      67              :     /// Scnedule event delivery to happen immediately (and synchronously).
      68              :     ///
      69              :     /// Use when it is imperative that some events are to be delivered because
      70              :     /// they will not be delivered soon after (e.g. device shutdown events or
      71              :     /// fabric removal events).
      72              :     ///
      73              :     /// This can be done either for a specific fabric, identified by the provided
      74              :     /// FabricIndex, or across all fabrics if no FabricIndex is provided.
      75              :     virtual void ScheduleUrgentEventDeliverySync(std::optional<FabricIndex> fabricIndex = std::nullopt) = 0;
      76              : 
      77              :     /// Generates the given event.
      78              :     ///
      79              :     /// Events are generally expected to be sent to subscribed clients and also
      80              :     /// be available for read later until they get overwritten by new events
      81              :     /// that are being generated.
      82              :     virtual CHIP_ERROR GenerateEvent(EventLoggingDelegate * eventPayloadWriter, const EventOptions & options,
      83              :                                      EventNumber & generatedEventNumber) = 0;
      84              : 
      85              :     /// Returns the monotonic startup timestamp used by the event system.
      86              :     ///
      87              :     /// This timestamp represents the "time 0" for system-time event timestamps.
      88              :     /// Returns zero if the event system has not been initialized yet.
      89              :     virtual System::Clock::Milliseconds64 GetMonotonicStartupTime() const = 0;
      90              : 
      91              :     // Convenience methods for event logging using cluster-object structures
      92              :     //
      93              :     // On error, these log and return nullopt.
      94              :     template <typename T>
      95           56 :     std::optional<EventNumber> GenerateEvent(const T & eventData, EndpointId endpointId)
      96              :     {
      97           56 :         internal::SimpleEventPayloadWriter<T> eventPayloadWriter(eventData);
      98           56 :         constexpr bool isFabricSensitiveEvent = DataModel::IsFabricScoped<T>::value;
      99           56 :         return internal::GenerateEvent({ endpointId, eventData }, *this, eventPayloadWriter, isFabricSensitiveEvent);
     100           56 :     }
     101              : };
     102              : 
     103              : } // namespace DataModel
     104              : } // namespace app
     105              : } // namespace chip