1 /* 2 * Copyright (C) 2020 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 CHPP_SERVICES_H_ 18 #define CHPP_SERVICES_H_ 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 24 #include "chpp/app.h" 25 #include "chpp/macros.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /************************************************ 32 * Public Definitions 33 ***********************************************/ 34 35 #if defined(CHPP_SERVICE_ENABLED_WWAN) || \ 36 defined(CHPP_SERVICE_ENABLED_WIFI) || defined(CHPP_SERVICE_ENABLED_GNSS) 37 #define CHPP_SERVICE_ENABLED 38 #endif 39 40 /** 41 * Uses chppAllocServiceNotification() to allocate a variable-length response 42 * message of a specific type. 43 * 44 * @param type Type of notification which includes an arrayed member. 45 * @param count number of items in the array of arrayField. 46 * @param arrayField The arrayed member field. 47 * 48 * @return Pointer to allocated memory 49 */ 50 #define chppAllocServiceNotificationTypedArray(type, count, arrayField) \ 51 (type *)chppAllocServiceNotification( \ 52 sizeof(type) + (count)*sizeof_member(type, arrayField[0])) 53 54 /** 55 * Uses chppAllocServiceNotification() to allocate a response message of a 56 * specific type and its corresponding length. 57 * 58 * @param type Type of notification. 59 * 60 * @return Pointer to allocated memory 61 */ 62 #define chppAllocServiceNotificationFixed(type) \ 63 (type *)chppAllocServiceNotification(sizeof(type)) 64 65 /** 66 * Uses chppAllocServiceResponse() to allocate a variable-length response 67 * message of a specific type. 68 * 69 * @param requestHeader client request header, as per 70 * chppAllocServiceResponse(). 71 * @param type Type of response which includes an arrayed member. 72 * @param count number of items in the array of arrayField. 73 * @param arrayField The arrayed member field. 74 * 75 * @return Pointer to allocated memory 76 */ 77 #define chppAllocServiceResponseTypedArray(requestHeader, type, count, \ 78 arrayField) \ 79 (type *)chppAllocServiceResponse( \ 80 requestHeader, \ 81 sizeof(type) + (count)*sizeof_member(type, arrayField[0])) 82 83 /** 84 * Uses chppAllocServiceResponse() to allocate a response message of a specific 85 * type and its corresponding length. 86 * 87 * @param requestHeader client request header, as per 88 * chppAllocServiceResponse(). 89 * @param type Type of response. 90 * 91 * @return Pointer to allocated memory 92 */ 93 #define chppAllocServiceResponseFixed(requestHeader, type) \ 94 (type *)chppAllocServiceResponse(requestHeader, sizeof(type)) 95 96 /** 97 * Maintains the basic state of a service. 98 * This is expected to be included in the state of each service. 99 */ 100 struct ChppServiceState { 101 struct ChppAppState *appContext; // Pointer to app layer context 102 uint8_t handle; // Handle number for this service 103 104 uint8_t openState; // As defined in enum ChppOpenState 105 }; 106 107 /************************************************ 108 * Public functions 109 ***********************************************/ 110 111 /** 112 * Registers common services with the CHPP app layer. These services are enabled 113 * by CHPP_SERVICE_ENABLED_xxxx definitions. This function is automatically 114 * called by chppAppInit(). 115 * 116 * @param context State of the app layer. 117 */ 118 void chppRegisterCommonServices(struct ChppAppState *context); 119 120 /** 121 * Deregisters common services with the CHPP app layer. These services are 122 * enabled by CHPP_SERVICE_ENABLED_xxxx definitions. This function is 123 * automatically called by chppAppInit(). 124 * 125 * @param context State of the app layer. 126 */ 127 void chppDeregisterCommonServices(struct ChppAppState *context); 128 129 /** 130 * Registers a new service on CHPP. This function is to be called by the 131 * platform initialization code for every non-common service available on a 132 * server (if any), i.e. except those that are registered through 133 * chppRegisterCommonServices(). 134 * 135 * Note that the maximum number of services that can be registered on a platform 136 * can specified as CHPP_MAX_REGISTERED_SERVICES by the initialization code. 137 * Otherwise, a default value will be used. 138 * 139 * @param appContext State of the app layer. 140 * @param serviceContext State of the service instance. 141 * @param serviceState State variable of the client. 142 * @param newService The service to be registered on this platform. 143 */ 144 void chppRegisterService(struct ChppAppState *appContext, void *serviceContext, 145 struct ChppServiceState *serviceState, 146 const struct ChppService *newService); 147 148 /** 149 * Allocates a service notification of a specified length. 150 * 151 * It is expected that for most use cases, the 152 * chppAllocServiceNotificationFixed() or 153 * chppAllocServiceNotificationTypedArray() macros shall be used rather than 154 * calling this function directly. 155 * 156 * @param len Length of the notification (including header) in bytes. Note 157 * that the specified length must be at least equal to the length of the app 158 * layer header. 159 * 160 * @return Pointer to allocated memory 161 */ 162 struct ChppAppHeader *chppAllocServiceNotification(size_t len); 163 164 /** 165 * Allocates a service response message of a specified length, populating the 166 * (app layer) service response header according to the provided client request 167 * (app layer) header. 168 * 169 * It is expected that for most use cases, the chppAllocServiceResponseFixed() 170 * or chppAllocServiceResponseTypedArray() macros shall be used rather than 171 * calling this function directly. 172 * 173 * @param requestHeader Client request header. 174 * @param len Length of the response message (including header) in bytes. Note 175 * that the specified length must be at least equal to the length of the app 176 * layer header. 177 * 178 * @return Pointer to allocated memory 179 */ 180 struct ChppAppHeader *chppAllocServiceResponse( 181 const struct ChppAppHeader *requestHeader, size_t len); 182 183 /** 184 * This function shall be called for all incoming client requests in order to 185 * A) Timestamp them, and 186 * B) Save their Transaction ID 187 * as part of the request/response's ChppRequestResponseState struct. 188 * 189 * This function prints an error message if a duplicate request is received 190 * while outstanding request is still pending without a response. 191 * 192 * @param rRStateState State of the current request/response. 193 * @param requestHeader Client request header. 194 */ 195 void chppServiceTimestampRequest(struct ChppRequestResponseState *rRState, 196 struct ChppAppHeader *requestHeader); 197 198 /** 199 * This function shall be called for the final service response to a client 200 * request in order to 201 * A) Timestamp them, and 202 * B) Mark them as fulfilled 203 * part of the request/response's ChppRequestResponseState struct. 204 * 205 * For most responses, it is expected that chppSendTimestampedResponseOrFail() 206 * shall be used to both timestamp and send the response in one shot. 207 * 208 * @param rRState State of the current request/response. 209 * @return The last response time (CHPP_TIME_NONE for the first response). 210 */ 211 uint64_t chppServiceTimestampResponse(struct ChppRequestResponseState *rRState); 212 213 /** 214 * Timestamps a service response using chppServiceTimestampResponse() and 215 * enqueues it using chppEnqueueTxDatagramOrFail(). 216 * 217 * Refer to their respective documentation for details. 218 * 219 * This function logs an error message if a response is attempted without an 220 * outstanding request. 221 * 222 * @param serviceState State of the service sending the response service. 223 * @param rRState State of the current request/response. 224 * @param buf Datagram payload allocated through chppMalloc. Cannot be null. 225 * @param len Datagram length in bytes. 226 * 227 * @return True informs the sender that the datagram was successfully enqueued. 228 * False informs the sender that the queue was full and the payload discarded. 229 */ 230 bool chppSendTimestampedResponseOrFail(struct ChppServiceState *serviceState, 231 struct ChppRequestResponseState *rRState, 232 void *buf, size_t len); 233 234 #ifdef __cplusplus 235 } 236 #endif 237 238 #endif // CHPP_SERVICES_H_ 239