1da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/* 2da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Copyright (C) 2016 The Android Open Source Project 3da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 4da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Licensed under the Apache License, Version 2.0 (the "License"); 5da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * you may not use this file except in compliance with the License. 6da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * You may obtain a copy of the License at 7da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 8da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * http://www.apache.org/licenses/LICENSE-2.0 9da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 10da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Unless required by applicable law or agreed to in writing, software 11da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * distributed under the License is distributed on an "AS IS" BASIS, 12da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * See the License for the specific language governing permissions and 14da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * limitations under the License. 15da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 16da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 17da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#ifndef _CHRE_EVENT_H_ 18da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define _CHRE_EVENT_H_ 19da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 20da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 21da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Context Hub Runtime Environment API dealing with events and messages. 22da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 23da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 24da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 25da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#include <stdbool.h> 26da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#include <stdint.h> 27da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#include <stdlib.h> 28da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 29da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#ifdef __cplusplus 30da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddieextern "C" { 31da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#endif 32da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 33da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 34da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The CHRE implementation is required to provide the following 35da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * preprocessor defines via the build system. 36da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 37da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MAX_SIZE: The maximum size, in bytes, allowed for 38da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * a message sent to chreSendMessageToHost(). This must be at least 39da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE. 40da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 41da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 42da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#ifndef CHRE_MESSAGE_TO_HOST_MAX_SIZE 43da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#error CHRE_MESSAGE_TO_HOST_MAX_SIZE must be defined by the Context Hub Runtime Environment implementation 44da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#endif 45da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 46da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 47da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The minimum size, in bytes, any CHRE implementation will 48da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * use for CHRE_MESSAGE_TO_HOST_MAX_SIZE. 49da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 50da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE 128 51da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 52da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#if CHRE_MESSAGE_TO_HOST_MAX_SIZE < CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE 53da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#error CHRE_MESSAGE_TO_HOST_MAX_SIZE is too small. 54da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#endif 55da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 56da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 57da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The lowest numerical value legal for a user-defined event. 58da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 59da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The system reserves all event values from 0 to 0x7FFF, inclusive. 60da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * User events may use any value in the range 0x8000 to 0xFFFF, inclusive. 61da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 62da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Note that the same event values might be used by different nanoapps 63da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * for different meanings. This is not a concern, as these values only 64da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * have meaning when paired with the originating nanoapp. 65da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 66da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_FIRST_USER_VALUE UINT16_C(0x8000) 67da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 68da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 69da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * nanoappHandleEvent argument: struct chreMessageFromHostData 70da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 71da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The format of the 'message' part of this structure is left undefined, 72da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * and it's up to the nanoapp and host to have an established protocol 73da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * beforehand. 74da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 75da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_MESSAGE_FROM_HOST UINT16_C(0x0001) 76da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 77da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 78da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * nanoappHandleEvent argument: 'cookie' given to chreTimerSet() method. 79da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 80da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Indicates that a timer has elapsed, in accordance with how chreTimerSet() was 81da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * invoked. 82da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 83da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_TIMER UINT16_C(0x0002) 84da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 85da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 86da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * First possible value for CHRE_EVENT_SENSOR events. 87da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 88da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This allows us to separately define our CHRE_EVENT_SENSOR_* events in 89da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * chre_sensor.h, without fear of collision with other event values. 90da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 91da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_SENSOR_FIRST_EVENT UINT16_C(0x0100) 92da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 93da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 94da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Last possible value for CHRE_EVENT_SENSOR events. 95da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 96da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This allows us to separately define our CHRE_EVENT_SENSOR_* events in 97da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * chre_sensor.h, without fear of collision with other event values. 98da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 99da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_SENSOR_LAST_EVENT UINT16_C(0x02FF) 100da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 101da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 102da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * First in a range of values dedicated for internal CHRE implementation usage. 103da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 104da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * If a CHRE wishes to use events internally, any values within this range 105da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * are assured not to be taken by future CHRE API additions. 106da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 107da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_INTERNAL_FIRST_EVENT UINT16_C(0x7E00) 108da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 109da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 110da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Last in a range of values dedicated for internal CHRE implementation usage. 111da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 112da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * If a CHRE wishes to use events internally, any values within this range 113da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * are assured not to be taken by future CHRE API additions. 114da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 115da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#define CHRE_EVENT_INTERNAL_LAST_EVENT UINT16_C(0x7FFF) 116da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 117da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 118da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 119da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_EVENT_MESSAGE_FROM_HOST 120da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 121da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddiestruct chreMessageFromHostData { 122da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie /** 123da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Message type (NOTE: not implemented correctly in the Android N release). 124da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 125da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * In future releases, this will be a message type provided by the host. 126da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 127da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie uint32_t reservedMessageType; 128da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 129da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie /** 130da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The size, in bytes of the following 'message'. 131da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 132da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This can be 0. 133da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 134da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie uint32_t messageSize; 135da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 136da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie /** 137da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * The message from the host. 138da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 139da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * These contents are of a format that the host and nanoapp must have 140da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * established beforehand. 141da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 142da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This data is 'messageSize' bytes in length. Note that if 'messageSize' 143da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * is 0, this might be NULL. 144da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 145da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie const void *message; 146da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie}; 147da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 148da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 149da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Callback which frees data associated with an event. 150da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 151da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This callback is (optionally) provided to the chreSendEvent() method as 152da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * a means for freeing the event data and performing any other cleanup 153da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * necessary when the event is completed. When this callback is invoked, 154da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 'eventData' is no longer needed and can be released. 155da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 156da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param eventType The 'eventType' argument from chreSendEvent(). 157da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param eventData The 'eventData' argument from chreSendEvent(). 158da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 159da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @see chreSendEvent 160da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 161da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddietypedef void (chreEventCompleteFunction)(uint16_t eventType, void *eventData); 162da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 163da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 164da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Callback which frees a message. 165da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 166da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This callback is (optionally) provided to the chreSendMessageToHost() method 167da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * as a means for freeing the message. When this callback is invoked, 168da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 'message' is no longer needed and can be released. Note that this in 169da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * no way assures that said message did or did not make it to the host, simply 170da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * that this memory is no longer needed. 171da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 172da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param message The 'message' argument from chreSendMessageToHost(). 173da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param messageSize The 'messageSize' argument from chreSendMessageToHost(). 174da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 175da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @see chreSendMessageToHost 176da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 177da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddietypedef void (chreMessageFreeFunction)(void *message, size_t messageSize); 178da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 179da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 180da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 181da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 182da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Enqueue an event to be sent to another nanoapp. 183da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 184da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Note: This version of the API does not give an easy means to discover 185da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * another nanoapp's instance ID. For now, events will need to be sent to/from 186da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * the host to initially discover these IDs. 187da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 188da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param eventType This is a user-defined event type, of at least the 189da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * value CHRE_EVENT_FIRST_USER_VALUE. It is illegal to attempt to use any 190da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * of the CHRE_EVENT_* values reserved for the CHRE. 191da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param eventData A pointer value that will be understood by the receiving 192da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * app. Note that NULL is perfectly acceptable. It also is not required 193da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * that this be a valid pointer, although if this nanoapp is intended to 194da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * work on arbitrary CHRE implementations, then the size of a 195da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * pointer cannot be assumed to be a certain size. Note that the caller 196da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * no longer owns this memory after the call. 197da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param freeCallback A pointer to a callback function. After the lifetime 198da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * of 'eventData' is over (either through successful delivery or the event 199da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * being dropped), this callback will be invoked. This argument is allowed 200da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * to be NULL, in which case no callback will be invoked. 201da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param targetInstanceId The ID of the instance we're delivering this event 202da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * to. Note that this is allowed to be our own instance. 203da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @returns true if the event was enqueued, false otherwise. Note that even 204da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * if this method returns 'false', the 'freeCallback' will be invoked, 205da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * if non-NULL. Note in the 'false' case, the 'freeCallback' may be 206da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * invoked directly from within chreSendEvent(), so it's necessary 207da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * for nanoapp authors to avoid possible recursion with this. 208da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 209da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @see chreEventDataFreeFunction 210da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 211da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddiebool chreSendEvent(uint16_t eventType, void *eventData, 212da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie chreEventCompleteFunction *freeCallback, 213da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie uint32_t targetInstanceId); 214da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 215da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie/** 216da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Send a message to the host. 217da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 218da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This message is by definition arbitrarily defined. Since we're not 219da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * just a passing a pointer to memory around the system, but need to copy 220da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * this into various buffers to send it to the host, the CHRE 221da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * implementation cannot be asked to support an arbitrarily large message 222da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * size. As a result, we have the CHRE implementation define 223da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MAX_SIZE. 224da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 225da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MAX_SIZE is not given a value by the Platform API. The 226da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Platform API does define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, and requires 227da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * that CHRE_MESSAGE_TO_HOST_MAX_SIZE is at least that value. 228da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 229da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * As a result, if your message sizes are all less than 230da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, then you have no concerns on any 231da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE implementation. If your message sizes are larger, you'll need to 232da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * come up with a strategy for splitting your message across several calls 233da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * to this method. As long as that strategy works for 234da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, it will work across all CHRE 235da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * implementations (although on some implementations less calls to this 236da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * method may be necessary). 237da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 238da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param message Pointer to a block of memory to send to the host. 239da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * NULL is acceptable only if messageSize is 0. If non-NULL, this 240da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * must be a legitimate pointer (that is, unlike chreSendEvent(), a small 241da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * integral value cannot be cast to a pointer for this). Note that the 242da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * caller no longer owns this memory after the call. 243da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param messageSize The size, in bytes, of the given message. 244da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * This cannot exceed CHRE_MESSAGE_TO_HOST_MAX_SIZE. 245da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param reservedMessageType Message type sent to the app on the host. 246da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * NOTE: In the N release, there is a bug in some HAL implementations 247da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * where this data does not make it to the app running on the host. 248da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Nanoapps cannot trust this across all platforms for N, but that 249da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * will be fixed in O. 250da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @param freeCallback A pointer to a callback function. After the lifetime 251da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * of 'message' is over (which does not assure that 'message' made it to 252da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * the host, just that the transport layer no longer needs this memory), 253da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * this callback will be invoked. This argument is allowed 254da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * to be NULL, in which case no callback will be invoked. 255da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @returns true if the message was accepted for transmission, false otherwise. 256da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * Note that even if this method returns 'false', the 'freeCallback' will 257da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * be invoked, if non-NULL. In either case, the 'freeCallback' may be 258da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * invoked directly from within chreSendMessageToHost(), so it's necessary 259da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * for nanoapp authors to avoid possible recursion with this. 260da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * 261da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie * @see chreMessageFreeFunction 262da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie */ 263da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddiebool chreSendMessageToHost(void *message, uint32_t messageSize, 264da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie uint32_t reservedMessageType, 265da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie chreMessageFreeFunction *freeCallback); 266da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 267da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 268da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#ifdef __cplusplus 269da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie} 270da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#endif 271da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 272da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie#endif /* _CHRE_EVENT_H_ */ 273da192a4ae641e01a09a7b01ef9e274f65d225af8Brian Duddie 274