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_NANOAPP_H_
18 #define _CHRE_NANOAPP_H_
19 
20 /**
21  * Methods in the Context Hub Runtime Environment which must be implemented
22  * by the nanoapp.
23  */
24 
25 #include <stdbool.h>
26 #include <stdint.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33  * Method invoked by the CHRE when loading the nanoapp.
34  *
35  * Every CHRE method is legal to call from this method.
36  *
37  * @returns  'true' if the nanoapp successfully started.  'false' if the nanoapp
38  *     failed to properly initialize itself (for example, could not obtain
39  *     sufficient memory from the heap).  If this method returns 'false', the
40  *     nanoapp will be unloaded by the CHRE (and nanoappEnd will
41  *     _not_ be invoked in that case).
42  * @see nanoappEnd
43  */
44 bool nanoappStart(void);
45 
46 /**
47  * Method invoked by the CHRE when there is an event for this nanoapp.
48  *
49  * Every CHRE method is legal to call from this method.
50  *
51  * @param senderInstanceId  The Instance ID for the source of this event.
52  *     Note that this may be CHRE_INSTANCE_ID, indicating that the event
53  *     was generated by the CHRE.
54  * @param eventType  The event type.  This might be one of the CHRE_EVENT_*
55  *     types defined in this API.  But it might also be a user-defined event.
56  * @param eventData  The associated data, if any, for this specific type of
57  *     event.  From the nanoapp's perspective, this eventData's lifetime ends
58  *     when this method returns, and thus any data the nanoapp wishes to
59  *     retain must be copied.  Note that interpretation of event data is
60  *     given by the event type, and for some events may not be a valid
61  *     pointer.  See documentation of the specific CHRE_EVENT_* types for how to
62  *     interpret this data for those.  Note that for user events, you will
63  *     need to establish what this data means.
64  */
65 void nanoappHandleEvent(uint32_t senderInstanceId, uint16_t eventType,
66                         const void* eventData);
67 
68 /**
69  * Method invoked by the CHRE when unloading the nanoapp.
70  *
71  * It is not valid to attempt to send events or messages, or to invoke functions
72  * which will generate events to this app, within the nanoapp implementation of
73  * this function.  That means it is illegal for the nanoapp invoke any of the
74  * following:
75  * - chreSendEvent()
76  * - chreSendMessageToHost()
77  * - chreSensorConfigure()
78  * - chreSensorConfigureModeOnly()
79  * - chreTimerSet()
80  *
81  * @see nanoappStart
82  */
83 void nanoappEnd(void);
84 
85 
86 #ifdef __cplusplus
87 }
88 #endif
89 
90 #endif  /* _CHRE_NANOAPP_H_ */
91