Changed URIBeaconConfigService.h to work with ST board
Fork of BLE_API by
GattClient.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef __GATT_CLIENT_H__ 00018 #define __GATT_CLIENT_H__ 00019 00020 #include "Gap.h" 00021 #include "GattAttribute.h" 00022 #include "ServiceDiscovery.h" 00023 00024 #include "GattCallbackParamTypes.h" 00025 00026 class GattClient { 00027 public: 00028 typedef void (*ReadCallback_t)(const GattReadCallbackParams *params); 00029 00030 enum WriteOp_t { 00031 GATT_OP_WRITE_REQ = 0x01, /**< Write Request. */ 00032 GATT_OP_WRITE_CMD = 0x02, /**< Write Command. */ 00033 }; 00034 00035 typedef void (*WriteCallback_t)(const GattWriteCallbackParams *params); 00036 00037 typedef void (*HVXCallback_t)(const GattHVXCallbackParams *params); 00038 00039 /* 00040 * The following functions are meant to be overridden in the platform-specific sub-class. 00041 */ 00042 public: 00043 /** 00044 * Launch service discovery. Once launched, application callbacks will be 00045 * invoked for matching services/characteristics. isServiceDiscoveryActive() 00046 * can be used to determine status; and a termination callback (if setup) 00047 * will be invoked at the end. Service discovery can be terminated prematurely 00048 * if needed using terminateServiceDiscovery(). 00049 * 00050 * @param connectionHandle 00051 * Handle for the connection with the peer. 00052 * @param sc 00053 * This is the application callback for matching service. Taken as 00054 * NULL by default. Note: service discovery may still be active 00055 * when this callback is issued; calling asynchronous BLE-stack 00056 * APIs from within this application callback might cause the 00057 * stack to abort service discovery. If this becomes an issue, it 00058 * may be better to make local copy of the discoveredService and 00059 * wait for service discovery to terminate before operating on the 00060 * service. 00061 * @param cc 00062 * This is the application callback for matching characteristic. 00063 * Taken as NULL by default. Note: service discovery may still be 00064 * active when this callback is issued; calling asynchronous 00065 * BLE-stack APIs from within this application callback might cause 00066 * the stack to abort service discovery. If this becomes an issue, 00067 * it may be better to make local copy of the discoveredCharacteristic 00068 * and wait for service discovery to terminate before operating on the 00069 * characteristic. 00070 * @param matchingServiceUUID 00071 * UUID based filter for specifying a service in which the application is 00072 * interested. By default it is set as the wildcard UUID_UNKNOWN, 00073 * in which case it matches all services. If characteristic-UUID 00074 * filter (below) is set to the wildcard value, then a service 00075 * callback will be invoked for the matching service (or for every 00076 * service if the service filter is a wildcard). 00077 * @param matchingCharacteristicUUIDIn 00078 * UUID based filter for specifying characteristic in which the application 00079 * is interested. By default it is set as the wildcard UUID_UKNOWN 00080 * to match against any characteristic. If both service-UUID 00081 * filter and characteristic-UUID filter are used with non- wildcard 00082 * values, then only a single characteristic callback is 00083 * invoked for the matching characteristic. 00084 * 00085 * @note Using wildcard values for both service-UUID and characteristic- 00086 * UUID will result in complete service discovery--callbacks being 00087 * called for every service and characteristic. 00088 * 00089 * @note Providing NULL for the characteristic callback will result in 00090 * characteristic discovery being skipped for each matching 00091 * service. This allows for an inexpensive method to discover only 00092 * services. 00093 * 00094 * @return 00095 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. 00096 */ 00097 virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle, 00098 ServiceDiscovery::ServiceCallback_t sc = NULL, 00099 ServiceDiscovery::CharacteristicCallback_t cc = NULL, 00100 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), 00101 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { 00102 /* avoid compiler warnings about unused variables */ 00103 (void)connectionHandle; 00104 (void)sc; 00105 (void)cc; 00106 (void)matchingServiceUUID; 00107 (void)matchingCharacteristicUUIDIn; 00108 00109 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ 00110 } 00111 00112 /** 00113 * Launch service discovery for services. Once launched, service discovery will remain 00114 * active with service-callbacks being issued back into the application for matching 00115 * services. isServiceDiscoveryActive() can be used to 00116 * determine status; and a termination callback (if setup) will be invoked 00117 * at the end. Service discovery can be terminated prematurely if needed 00118 * using terminateServiceDiscovery(). 00119 * 00120 * @param connectionHandle 00121 * Handle for the connection with the peer. 00122 * @param sc 00123 * This is the application callback for matching service. Note: service discovery may still be active 00124 * when this callback is issued; calling asynchronous BLE-stack 00125 * APIs from within this application callback might cause the 00126 * stack to abort service discovery. If this becomes an issue, it 00127 * may be better to make local copy of the discoveredService and 00128 * wait for service discovery to terminate before operating on the 00129 * service. 00130 * @param matchingServiceUUID 00131 * UUID based filter for specifying a service in which the application is 00132 * interested. By default it is set as the wildcard UUID_UNKNOWN, 00133 * in which case it matches all services. 00134 * 00135 * @return 00136 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. 00137 */ 00138 virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, 00139 ServiceDiscovery::ServiceCallback_t callback, 00140 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { 00141 return launchServiceDiscovery(connectionHandle, callback, NULL, matchingServiceUUID); /* We take advantage of the property 00142 * that providing NULL for the characteristic callback will result in 00143 * characteristic discovery being skipped for each matching 00144 * service. This allows for an inexpensive method to discover only 00145 * services. Porter(s) are free to override this. */ 00146 } 00147 00148 /** 00149 * Launch service discovery for services. Once launched, service discovery will remain 00150 * active with service-callbacks being issued back into the application for matching 00151 * services. isServiceDiscoveryActive() can be used to 00152 * determine status; and a termination callback (if setup) will be invoked 00153 * at the end. Service discovery can be terminated prematurely if needed 00154 * using terminateServiceDiscovery(). 00155 * 00156 * @param connectionHandle 00157 * Handle for the connection with the peer. 00158 * @param sc 00159 * This is the application callback for matching service. Note: service discovery may still be active 00160 * when this callback is issued; calling asynchronous BLE-stack 00161 * APIs from within this application callback might cause the 00162 * stack to abort service discovery. If this becomes an issue, it 00163 * may be better to make local copy of the discoveredService and 00164 * wait for service discovery to terminate before operating on the 00165 * service. 00166 * @param startHandle, endHandle 00167 * Handle range within which to limit the search 00168 * 00169 * @return 00170 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. 00171 */ 00172 virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, 00173 ServiceDiscovery::ServiceCallback_t callback, 00174 GattAttribute::Handle_t startHandle, 00175 GattAttribute::Handle_t endHandle) { 00176 /* avoid compiler warnings about unused variables */ 00177 (void)connectionHandle; 00178 (void)callback; 00179 (void)startHandle; 00180 (void)endHandle; 00181 00182 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ 00183 } 00184 00185 /** 00186 * Is service-discovery currently active? 00187 */ 00188 virtual bool isServiceDiscoveryActive(void) const { 00189 return false; /* Requesting action from porter(s): override this API if this capability is supported. */ 00190 } 00191 00192 /** 00193 * Terminate an ongoing service-discovery. This should result in an 00194 * invocation of the TerminationCallback if service-discovery is active. 00195 */ 00196 virtual void terminateServiceDiscovery(void) { 00197 /* Requesting action from porter(s): override this API if this capability is supported. */ 00198 } 00199 00200 /* Initiate a Gatt Client read procedure by attribute-handle. */ 00201 virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const { 00202 /* avoid compiler warnings about unused variables */ 00203 (void)connHandle; 00204 (void)attributeHandle; 00205 (void)offset; 00206 00207 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ 00208 } 00209 00210 /** 00211 * Initiate a GATT Client write procedure. 00212 * 00213 * @param[in] cmd 00214 * Command can be either a write-request (which generates a 00215 * matching response from the peripheral), or a write-command, 00216 * which doesn't require the connected peer to respond. 00217 * @param[in] connHandle 00218 * Connection handle. 00219 * @param[in] attributeHandle 00220 * handle for the target attribtue on the remote GATT server. 00221 * @param[in] length 00222 * length of the new value. 00223 * @param[in] value 00224 * new value being written. 00225 */ 00226 virtual ble_error_t write(GattClient::WriteOp_t cmd, 00227 Gap::Handle_t connHandle, 00228 GattAttribute::Handle_t attributeHandle, 00229 size_t length, 00230 const uint8_t *value) const { 00231 /* avoid compiler warnings about unused variables */ 00232 (void)cmd; 00233 (void)connHandle; 00234 (void)attributeHandle; 00235 (void)length; 00236 (void)value; 00237 00238 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ 00239 } 00240 00241 /* Event callback handlers. */ 00242 public: 00243 /** 00244 * Setup a callback for read response events. 00245 */ 00246 void onDataRead(ReadCallback_t callback) { 00247 onDataReadCallback = callback; 00248 } 00249 00250 /** 00251 * Setup a callback for write response events. 00252 * @Note: write commands (issued using writeWoResponse) don't generate a response. 00253 */ 00254 void onDataWrite(WriteCallback_t callback) { 00255 onDataWriteCallback = callback; 00256 } 00257 00258 /** 00259 * Setup callback for when serviceDiscovery terminates. 00260 */ 00261 virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) { 00262 (void)callback; /* avoid compiler warnings about ununsed variables */ 00263 00264 /* Requesting action from porter(s): override this API if this capability is supported. */ 00265 } 00266 00267 /** 00268 * Setup a callback for when GattClient receives an update event 00269 * corresponding to a change in value of a characteristic on the remote 00270 * GattServer. 00271 */ 00272 void onHVX(HVXCallback_t callback) { 00273 onHVXCallback = callback; 00274 } 00275 00276 protected: 00277 GattClient() { 00278 /* empty */ 00279 } 00280 00281 /* Entry points for the underlying stack to report events back to the user. */ 00282 public: 00283 void processReadResponse(const GattReadCallbackParams *params) { 00284 if (onDataReadCallback) { 00285 onDataReadCallback(params); 00286 } 00287 } 00288 00289 void processWriteResponse(const GattWriteCallbackParams *params) { 00290 if (onDataWriteCallback) { 00291 onDataWriteCallback(params); 00292 } 00293 } 00294 00295 void processHVXEvent(const GattHVXCallbackParams *params) { 00296 if (onHVXCallback) { 00297 onHVXCallback(params); 00298 } 00299 } 00300 00301 protected: 00302 ReadCallback_t onDataReadCallback; 00303 WriteCallback_t onDataWriteCallback; 00304 HVXCallback_t onHVXCallback; 00305 00306 private: 00307 /* disallow copy and assignment */ 00308 GattClient(const GattClient &); 00309 GattClient& operator=(const GattClient &); 00310 }; 00311 00312 #endif // ifndef __GATT_CLIENT_H__
Generated on Tue Jul 12 2022 18:14:55 by 1.7.2