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) || \ 37 defined(CHPP_SERVICE_ENABLED_GNSS) || defined(CHPP_SERVICE_ENABLED_VENDOR) 38 #define CHPP_SERVICE_ENABLED 39 #endif 40 41 /** 42 * Allocates a service request message of a specific type and its corresponding 43 * length. 44 * 45 * @param serviceState State of the service. 46 * @param type Type of response. 47 * 48 * @return Pointer to allocated memory. 49 */ 50 #define chppAllocServiceRequestFixed(serviceState, type) \ 51 (type *)chppAllocServiceRequest(serviceState, sizeof(type)) 52 53 /** 54 * Allocate a variable-length service request message of a specific type. 55 * 56 * @param serviceState State of the service. 57 * @param type Type of response which includes an arrayed member. 58 * @param count number of items in the array of arrayField. 59 * @param arrayField The arrayed member field. 60 * 61 * @return Pointer to allocated memory. 62 */ 63 #define chppAllocServiceRequestTypedArray(serviceState, type, count, \ 64 arrayField) \ 65 (type *)chppAllocServiceRequest( \ 66 serviceState, sizeof(type) + (count)*sizeof_member(type, arrayField[0])) 67 68 /** 69 * Allocates a variable-length notification of a specific type. 70 * 71 * @param type Type of notification 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 chppAllocServiceNotificationTypedArray(type, count, arrayField) \ 78 (type *)chppAllocServiceNotification( \ 79 sizeof(type) + (count)*sizeof_member(type, arrayField[0])) 80 81 /** 82 * Uses chppAllocServiceNotification() to allocate a response notification of a 83 * specific type and its corresponding length. 84 * 85 * @param type Type of notification. 86 * 87 * @return Pointer to allocated memory 88 */ 89 #define chppAllocServiceNotificationFixed(type) \ 90 (type *)chppAllocServiceNotification(sizeof(type)) 91 92 /************************************************ 93 * Public functions 94 ***********************************************/ 95 96 /** 97 * Registers common services with the CHPP app layer. These services are enabled 98 * by CHPP_SERVICE_ENABLED_xxxx definitions. This function is automatically 99 * called by chppAppInit(). 100 * 101 * @param context State of the app layer. 102 */ 103 void chppRegisterCommonServices(struct ChppAppState *context); 104 105 /** 106 * Deregisters common services with the CHPP app layer. These services are 107 * enabled by CHPP_SERVICE_ENABLED_xxxx definitions. This function is 108 * automatically called by chppAppInit(). 109 * 110 * @param context State of the app layer. 111 */ 112 void chppDeregisterCommonServices(struct ChppAppState *context); 113 114 /** 115 * Registers a new service on CHPP. This function is to be called by the 116 * platform initialization code for every non-common service available on a 117 * server (if any), i.e. except those that are registered through 118 * chppRegisterCommonServices(). 119 * 120 * outReqStates must point to an array of ChppOutgoingRequestState with 121 * ChppEndpointState.outReqCount elements. It must be NULL when the service 122 * does not send requests (ChppEndpointState.outReqCount = 0). 123 * 124 * inReqStates must point to an array of ChppIncomingRequestState with 125 * as many elements as the corresponding client can send. It must be NULL when 126 * the client does not send requests (ChppEndpointState.outReqCount = 0). 127 * 128 * Note that the maximum number of services that can be registered on a platform 129 * can specified as CHPP_MAX_REGISTERED_SERVICES by the initialization code. 130 * Otherwise, a default value will be used. 131 * 132 * @param appContext State of the app layer. 133 * @param serviceContext State of the service instance. 134 * @param serviceState State of the client. 135 * @param outReqStates List of outgoing request states. 136 * @param newService The service to be registered on this platform. 137 */ 138 void chppRegisterService(struct ChppAppState *appContext, void *serviceContext, 139 struct ChppEndpointState *serviceState, 140 struct ChppOutgoingRequestState *outReqStates, 141 const struct ChppService *newService); 142 143 /** 144 * Allocates a service notification of a specified length. 145 * 146 * It is expected that for most use cases, the 147 * chppAllocServiceNotificationFixed() or 148 * chppAllocServiceNotificationTypedArray() macros shall be used rather than 149 * calling this function directly. 150 * 151 * The caller must initialize at least the handle and command fields of the 152 * ChppAppHeader. 153 * 154 * @param len Length of the notification (including header) in bytes. Note 155 * that the specified length must be at least equal to the length of the 156 * app layer header. 157 * 158 * @return Pointer to allocated memory 159 */ 160 struct ChppAppHeader *chppAllocServiceNotification(size_t len); 161 162 /** 163 * Allocates a service request message of a specified length. 164 * 165 * It populates the request header, including the transaction number which is 166 * then incremented. 167 * 168 * For most use cases, the chppAllocServiceRequestFixed() or 169 * chppAllocServiceRequestTypedArray() macros shall be preferred. 170 * 171 * @param serviceState State of the service. 172 * @param len Length of the response message (including header) in bytes. Note 173 * that the specified length must be at least equal to the length of the 174 * app layer header. 175 * 176 * @return Pointer to allocated memory 177 */ 178 struct ChppAppHeader *chppAllocServiceRequest( 179 struct ChppEndpointState *serviceState, size_t len); 180 181 /** 182 * Allocates a specific service request command without any additional payload. 183 * 184 * @param serviceState State of the service. 185 * @param command Type of response. 186 * 187 * @return Pointer to allocated memory 188 */ 189 struct ChppAppHeader *chppAllocServiceRequestCommand( 190 struct ChppEndpointState *serviceState, uint16_t command); 191 192 /** 193 * Timestamps and enqueues a request. 194 * 195 * Note that the ownership of buf is taken from the caller when this method is 196 * invoked. 197 * 198 * @param serviceState State of the service sending the request. 199 * @param outReqState State of the request/response. 200 * @param buf Datagram payload allocated through chppMalloc. Cannot be null. 201 * @param len Datagram length in bytes. 202 * @param timeoutNs Time in nanoseconds before a timeout response is generated. 203 * Zero means no timeout response. 204 * 205 * @return True informs the sender that the datagram was successfully enqueued. 206 * False informs the sender that the queue was full and the payload 207 * discarded. 208 */ 209 bool chppServiceSendTimestampedRequestOrFail( 210 struct ChppEndpointState *serviceState, 211 struct ChppOutgoingRequestState *outReqState, void *buf, size_t len, 212 uint64_t timeoutNs); 213 214 /** 215 * Similar to chppServiceSendTimestampedRequestOrFail() but blocks execution 216 * until a response is received. Used for synchronous requests. 217 * 218 * @param serviceState State of the service sending the request. 219 * @param outReqState State of the request/response. 220 * @param buf Datagram payload allocated through chppMalloc. Cannot be null. 221 * @param len Datagram length in bytes. 222 * 223 * @return True informs the sender that the datagram was successfully enqueued. 224 * False informs the sender that the payload was discarded because 225 * either the queue was full, or the request timed out. 226 */ 227 bool chppServiceSendTimestampedRequestAndWait( 228 struct ChppEndpointState *serviceState, 229 struct ChppOutgoingRequestState *outReqState, void *buf, size_t len); 230 231 /** 232 * Same as chppClientSendTimestampedRequestAndWait() but with a specified 233 * timeout. 234 * 235 * @param serviceState State of the service sending the request. 236 * @param outReqState State of the request/response. 237 * @param buf Datagram payload allocated through chppMalloc. Cannot be null. 238 * @param len Datagram length in bytes. 239 * 240 * @return True informs the sender that the datagram was successfully enqueued. 241 * False informs the sender that the payload was discarded because 242 * either the queue was full, or the request timed out. 243 */ 244 bool chppServiceSendTimestampedRequestAndWaitTimeout( 245 struct ChppEndpointState *serviceState, 246 struct ChppOutgoingRequestState *outReqState, void *buf, size_t len, 247 uint64_t timeoutNs); 248 249 /** 250 * Closes any remaining open requests by simulating a timeout. 251 * 252 * This function is used when a service is reset. 253 * 254 * @param serviceState State of the service. 255 * @param service The service for which to clear out open requests. 256 * @param clearOnly If true, indicates that a timeout response shouldn't be 257 * sent. This must only be set if the requests are being cleared as 258 * part of the closing. 259 */ 260 void chppServiceCloseOpenRequests(struct ChppEndpointState *serviceState, 261 const struct ChppService *service, 262 bool clearOnly); 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif // CHPP_SERVICES_H_ 269