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_PLATFORM_PLATFORM_NANOAPP_H_
18 #define CHRE_PLATFORM_PLATFORM_NANOAPP_H_
19 
20 #include <cstddef>
21 #include <cstdint>
22 
23 #include "chre/target_platform/platform_nanoapp_base.h"
24 #include "chre/util/non_copyable.h"
25 #include "chre/util/system/debug_dump.h"
26 
27 namespace chre {
28 
29 /**
30  * The common interface to Nanoapp functionality that has platform-specific
31  * implementation but must be supported for every platform.
32  */
33 class PlatformNanoapp : public PlatformNanoappBase, public NonCopyable {
34  public:
35   /**
36    * Calls the start function of the nanoapp. For dynamically loaded nanoapps,
37    * this must also result in calling through to any of the nanoapp's static
38    * global constructors/init functions, etc., prior to invoking the
39    * nanoappStart.
40    *
41    * @return true if the app was able to start successfully
42    *
43    * @see nanoappStart
44    */
45   bool start();
46 
47   /**
48    * Passes an event to the nanoapp.
49    *
50    * @see nanoappHandleEvent
51    */
52   void handleEvent(uint32_t senderInstanceId, uint16_t eventType,
53                    const void *eventData);
54 
55   /**
56    * Calls the nanoapp's end callback. For dynamically loaded nanoapps, this
57    * must also result in calling through to any of the nanoapp's static global
58    * destructors, atexit functions, etc., after nanoappEnd returns. This is only
59    * valid to call after start() has returned true.
60    *
61    * This function must leave the nanoapp in a state where it can be started
62    * again via start().
63    *
64    * @see nanoappEnd
65    */
66   void end();
67 
68   /**
69    * Retrieves the nanoapp's 64-bit identifier. This function must always return
70    * a valid identifier - either the one supplied by the host via the HAL (from
71    * the header), or the authoritative value inside the nanoapp binary if one
72    * exists. In the event that both are available and they do not match, the
73    * platform implementation must return false from start().
74    */
75   uint64_t getAppId() const;
76 
77   /**
78    * Retrieves the nanoapp's own version number. The same restrictions apply
79    * here as for getAppId().
80    *
81    * @see #getAppId
82    */
83   uint32_t getAppVersion() const;
84 
85   /**
86    * Retrieves the API version that this nanoapp was compiled against.
87    */
88   uint32_t getTargetApiVersion() const;
89 
90   /**
91    * Returns true if the nanoapp supports permissions (i.e. minor version >=
92    * CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION).
93    */
94   bool supportsAppPermissions() const;
95 
96   /**
97    * Retrieves the nanoapp's permissions. If unsupported, returns with no
98    * permissions.
99    */
100   uint32_t getAppPermissions() const;
101 
102   /**
103    * Retrieves the human-friendly name for the nanoapp (null-terminated string).
104    */
105   const char *getAppName() const;
106 
107   /**
108    * Returns true if the nanoapp should not appear in the context hub HAL list
109    * of nanoapps, e.g. because it implements some device functionality purely
110    * beneath the HAL.
111    */
112   bool isSystemNanoapp() const;
113 
114   /**
115    * Prints state in a string buffer. Must only be called from the context of
116    * the main CHRE thread.
117    *
118    * @param debugDump The debug dump wrapper object where logs are printed
119    * into.
120    */
121   void logStateToBuffer(DebugDumpWrapper &debugDump) const;
122 
123  protected:
124   /**
125    * PlatformNanoapp's constructor is protected, as it must only exist within
126    * the context of the derived class chre::Nanoapp.
127    */
128   PlatformNanoapp() = default;
129 
130   /**
131    * Unloads the nanoapp from memory.
132    */
133   ~PlatformNanoapp();
134 };
135 
136 }  // namespace chre
137 
138 #endif  // CHRE_PLATFORM_PLATFORM_NANOAPP_H_
139