Home | History | Annotate | Download | only in pal 
      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