Home | History | Annotate | Download | only in core 
      1 /*
      2  * Copyright (C) 2016 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef CHRE_CORE_NANOAPP_H_
     18 #define CHRE_CORE_NANOAPP_H_
     19 
     20 #include <cinttypes>
     21 
     22 #include "chre/core/event.h"
     23 #include "chre/core/event_ref_queue.h"
     24 #include "chre/platform/platform_nanoapp.h"
     25 #include "chre/util/dynamic_vector.h"
     26 
     27 namespace chre {
     28 
     29 /**
     30  * A class that tracks the state of a Nanoapp including incoming events and
     31  * event registrations.
     32  *
     33  * Inheritance is used to separate the common interface with common
     34  * implementation part (chre::Nanoapp) from the common interface with
     35  * platform-specific implementation part (chre::PlatformNanoapp) from the purely
     36  * platform-specific part (chre::PlatformNanoappBase). However, this inheritance
     37  * relationship does *not* imply polymorphism, and this object must only be
     38  * referred to via the most-derived type, i.e. chre::Nanoapp.
     39  */
     40 class Nanoapp : public PlatformNanoapp {
     41  public:
     42   /**
     43    * @return The unique identifier for this Nanoapp instance
     44    */
     45   uint32_t getInstanceId() const {
     46     return mInstanceId;
     47   }
     48 
     49   /**
     50    * Assigns an instance ID to this Nanoapp. This must be called prior to
     51    * starting this Nanoapp.
     52    */
     53   void setInstanceId(uint32_t instanceId) {
     54     mInstanceId = instanceId;
     55   }
     56 
     57   /**
     58    * @return true if the nanoapp should receive broadcast events with the given
     59    *         type
     60    */
     61   bool isRegisteredForBroadcastEvent(uint16_t eventType) const;
     62 
     63   /**
     64    * Updates the Nanoapp's registration so that it will receive broadcast events
     65    * with the given event ID.
     66    *
     67    * @return true if the event is newly registered
     68    */
     69   bool registerForBroadcastEvent(uint16_t eventId);
     70 
     71   /**
     72    * Updates the Nanoapp's registration so that it will not receive broadcast
     73    * events with the given event ID.
     74    *
     75    * @return true if the event was previously registered
     76    */
     77   bool unregisterForBroadcastEvent(uint16_t eventId);
     78 
     79   /**
     80    * Adds an event to this nanoapp's queue of pending events.
     81    *
     82    * @param event
     83    */
     84   void postEvent(Event *event);
     85 
     86   /**
     87    * Indicates whether there are any pending events in this apps queue.
     88    *
     89    * @return true if there are events waiting to be processed
     90    */
     91   bool hasPendingEvent();
     92 
     93   /**
     94    * Configures whether nanoapp info events will be sent to the nanoapp.
     95    * Nanoapps are not sent nanoapp start/stop events by default.
     96    *
     97    * @param enable true if events are to be sent, false otherwise.
     98    */
     99   void configureNanoappInfoEvents(bool enable);
    100 
    101   /**
    102    * Configures whether host sleep events will be sent to the nanoapp. Nanoapps
    103    * are not sent sleep/awake events by default.
    104    *
    105    * @param enable true if events are to be sent, false otherwise.
    106    */
    107   void configureHostSleepEvents(bool enable);
    108 
    109   /**
    110    * Sends the next event in the queue to the nanoapp and returns the processed
    111    * event. The hasPendingEvent() method should be tested before invoking this.
    112    *
    113    * @return A pointer to the processed event
    114    */
    115   Event *processNextEvent();
    116 
    117   /**
    118    * Prints state in a string buffer. Must only be called from the context of
    119    * the main CHRE thread.
    120    *
    121    * @param buffer Pointer to the start of the buffer.
    122    * @param bufferPos Pointer to buffer position to start the print (in-out).
    123    * @param size Size of the buffer in bytes.
    124    *
    125    * @return true if entire log printed, false if overflow or error.
    126    */
    127   bool logStateToBuffer(char *buffer, size_t *bufferPos,
    128                         size_t bufferSize) const;
    129 
    130  private:
    131   uint32_t mInstanceId = kInvalidInstanceId;
    132 
    133   //! The set of broadcast events that this app is registered for.
    134   // TODO: Implement a set container and replace DynamicVector here. There may
    135   // also be a better way of handling this (perhaps we map event type to apps
    136   // who care about them).
    137   DynamicVector<uint16_t> mRegisteredEvents;
    138 
    139   EventRefQueue mEventQueue;
    140 };
    141 
    142 }
    143 
    144 #endif  // CHRE_CORE_NANOAPP_H_
    145