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_PAL_WWAN_H_ 18 #define CHRE_PAL_WWAN_H_ 19 20 /** 21 * @file 22 * Defines the interface between the common CHRE core system and the 23 * platform-specific WWAN module. 24 */ 25 26 #include <stdbool.h> 27 #include <stdint.h> 28 29 #include "chre_api/chre/wwan.h" 30 #include "chre/pal/system.h" 31 #include "chre/pal/version.h" 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /** 38 * Initial version of the CHRE WWAN PAL, tied to CHRE API v1.1. 39 */ 40 #define CHRE_PAL_WWAN_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0) 41 42 /** 43 * The version of the CHRE WWAN PAL defined in this header file. 44 */ 45 #define CHRE_PAL_WWAN_API_CURRENT_VERSION CHRE_PAL_WWAN_API_V1_0 46 47 struct chrePalWwanCallbacks { 48 /** 49 * Callback invoked to provide the result of a prior request to 50 * requestCellInfo in struct chrePalWwanApi. 51 * 52 * This function call passes ownership of the result's memory to the core 53 * CHRE system, i.e. the PAL module must not modify or free the provided 54 * data until the associated API function is called to release the memory. 55 * 56 * @param result 57 * 58 * @see chrePalWwanApi.requestCellInfo 59 * @see chrePalWwanApi.releaseCellInfoResult 60 */ 61 void (*cellInfoResultCallback)(struct chreWwanCellInfoResult *result); 62 }; 63 64 struct chrePalWwanApi { 65 /** 66 * Version of the module providing this API. This value should be 67 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 68 * API version constant (CHRE_PAL_WWAN_API_*) and the module-specific patch 69 * version. 70 */ 71 uint32_t moduleVersion; 72 73 /** 74 * Initializes the WWAN module. Initialization must complete synchronously. 75 * 76 * @param systemApi Structure containing CHRE system function pointers which 77 * the PAL implementation should prefer to use over equivalent 78 * functionality exposed by the underlying platform. The module does 79 * not need to deep-copy this structure; its memory remains 80 * accessible at least until after close() is called. 81 * @param callbacks Structure containing entry points to the core CHRE 82 * system. The module does not need to deep-copy this structure; its 83 * memory remains accessible at least until after close() is called. 84 * 85 * @return true if initialization was successful, false otherwise 86 */ 87 bool (*open)(const struct chrePalSystemApi *systemApi, 88 const struct chrePalWwanCallbacks *callbacks); 89 90 /** 91 * Performs clean shutdown of the WWAN module, usually done in preparation 92 * for stopping the CHRE. The WWAN module must ensure that it will not 93 * invoke any callbacks past this point, and complete any relevant teardown 94 * activities before returning from this function. 95 */ 96 void (*close)(void); 97 98 /** 99 * Retrieves information about the features supported by this module. The 100 * value returned from this function must not change for the duration of 101 * execution. 102 * 103 * @return See chreWwanGetCapabilities() 104 * 105 * @see chreWwanGetCapabilities() 106 */ 107 uint32_t (*getCapabilities)(void); 108 109 /** 110 * Initiates a request for information about the current serving cell and 111 * its neighbors. 112 * 113 * @return true if the request was accepted, in which case a subsequent call 114 * to cellInfoResultCallback will be used to communicate the result 115 * 116 * @see chreWwanGetCellInfoAsync() 117 * @see chrePalWwanCallbacks.cellInfoResultCallback 118 */ 119 bool (*requestCellInfo)(void); 120 121 /** 122 * Invoked when the core CHRE system no longer needs a raw measurement event 123 * structure that was provided to it via measurementEventCallback(). The 124 * GNSS module may use this to free associated memory, etc. 125 * 126 * @param result Result data to release 127 */ 128 void (*releaseCellInfoResult)(struct chreWwanCellInfoResult *result); 129 }; 130 131 /** 132 * Retrieve a handle for the CHRE WWAN PAL. 133 * 134 * @param requestedApiVersion The implementation of this function must return a 135 * pointer to a structure with the same major version as requested. 136 * 137 * @return Pointer to API handle, or NULL if a compatible API version is not 138 * supported by the module, or the API as a whole is not implemented. If 139 * non-NULL, the returned API handle must be valid as long as this 140 * module is loaded. 141 */ 142 const struct chrePalWwanApi *chrePalWwanGetApi(uint32_t requestedApiVersion); 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #endif // CHRE_PAL_WWAN_H_ 149