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
29extern "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 */
44bool 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 */
65void 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 */
83void nanoappEnd(void);
84
85
86#ifdef __cplusplus
87}
88#endif
89
90#endif  /* _CHRE_NANOAPP_H_ */
91