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              : 
      29              : #include <optional>
      30              : 
      31              : namespace chip {
      32              : namespace app {
      33              : namespace DataModel {
      34              : 
      35              : class EventsGenerator;
      36              : 
      37              : namespace internal {
      38              : template <typename T>
      39              : class SimpleEventPayloadWriter : public EventLoggingDelegate
      40              : {
      41              : public:
      42            4 :     SimpleEventPayloadWriter(const T & aEventData) : mEventData(aEventData){};
      43            3 :     CHIP_ERROR WriteEvent(chip::TLV::TLVWriter & aWriter) final override
      44              :     {
      45            3 :         return DataModel::Encode(aWriter, TLV::ContextTag(EventDataIB::Tag::kData), mEventData);
      46              :     }
      47              : 
      48              : private:
      49              :     const T & mEventData;
      50              : };
      51              : 
      52              : std::optional<EventNumber> GenerateEvent(const EventOptions & eventOptions, EventsGenerator & generator,
      53              :                                          EventLoggingDelegate & delegate, bool isFabricSensitiveEvent);
      54              : 
      55              : } // namespace internal
      56              : 
      57              : /// Exposes event generation capabilities.
      58              : ///
      59              : /// Allows callers to "generate events" which effectively notifies of an event having
      60              : /// ocurred.
      61              : class EventsGenerator
      62              : {
      63              : public:
      64          319 :     virtual ~EventsGenerator() = default;
      65              : 
      66              :     /// Scnedule event delivery to happen immediately (and synchronously).
      67              :     ///
      68              :     /// Use when it is imperative that some events are to be delivered because
      69              :     /// they will not be delivered soon after (e.g. device shutdown events or
      70              :     /// fabric removal events).
      71              :     ///
      72              :     /// This can be done either for a specific fabric, identified by the provided
      73              :     /// FabricIndex, or across all fabrics if no FabricIndex is provided.
      74              :     virtual void ScheduleUrgentEventDeliverySync(std::optional<FabricIndex> fabricIndex = std::nullopt) = 0;
      75              : 
      76              :     /// Generates the given event.
      77              :     ///
      78              :     /// Events are generally expected to be sent to subscribed clients and also
      79              :     /// be available for read later until they get overwritten by new events
      80              :     /// that are being generated.
      81              :     virtual CHIP_ERROR GenerateEvent(EventLoggingDelegate * eventPayloadWriter, const EventOptions & options,
      82              :                                      EventNumber & generatedEventNumber) = 0;
      83              : 
      84              :     // Convenience methods for event logging using cluster-object structures
      85              :     //
      86              :     // On error, these log and return nullopt.
      87              :     template <typename T>
      88            4 :     std::optional<EventNumber> GenerateEvent(const T & eventData, EndpointId endpointId)
      89              :     {
      90            4 :         internal::SimpleEventPayloadWriter<T> eventPayloadWriter(eventData);
      91            4 :         constexpr bool isFabricSensitiveEvent = DataModel::IsFabricScoped<T>::value;
      92            4 :         return internal::GenerateEvent({ endpointId, eventData }, *this, eventPayloadWriter, isFabricSensitiveEvent);
      93            4 :     }
      94              : };
      95              : 
      96              : } // namespace DataModel
      97              : } // namespace app
      98              : } // namespace chip