add "LE Device Address" 0x1B to advertising data types
Fork of BLE_API by
ble/GattClient.h@725:f4a355b35cf8, 2015-07-02 (annotated)
- Committer:
- rgrover1
- Date:
- Thu Jul 02 09:06:12 2015 +0100
- Revision:
- 725:f4a355b35cf8
- Parent:
- 720:ce8a760a4504
- Child:
- 727:1a1f5c5aedfe
Synchronized with git rev 417b857d
Author: Rohit Grover
changing a comment pattern to request action from porters.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
rgrover1 | 716:11b41f651697 | 1 | /* mbed Microcontroller Library |
rgrover1 | 716:11b41f651697 | 2 | * Copyright (c) 2006-2013 ARM Limited |
rgrover1 | 716:11b41f651697 | 3 | * |
rgrover1 | 716:11b41f651697 | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
rgrover1 | 716:11b41f651697 | 5 | * you may not use this file except in compliance with the License. |
rgrover1 | 716:11b41f651697 | 6 | * You may obtain a copy of the License at |
rgrover1 | 716:11b41f651697 | 7 | * |
rgrover1 | 716:11b41f651697 | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
rgrover1 | 716:11b41f651697 | 9 | * |
rgrover1 | 716:11b41f651697 | 10 | * Unless required by applicable law or agreed to in writing, software |
rgrover1 | 716:11b41f651697 | 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
rgrover1 | 716:11b41f651697 | 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
rgrover1 | 716:11b41f651697 | 13 | * See the License for the specific language governing permissions and |
rgrover1 | 716:11b41f651697 | 14 | * limitations under the License. |
rgrover1 | 716:11b41f651697 | 15 | */ |
rgrover1 | 716:11b41f651697 | 16 | |
rgrover1 | 716:11b41f651697 | 17 | #ifndef __GATT_CLIENT_H__ |
rgrover1 | 716:11b41f651697 | 18 | #define __GATT_CLIENT_H__ |
rgrover1 | 716:11b41f651697 | 19 | |
rgrover1 | 716:11b41f651697 | 20 | #include "Gap.h" |
rgrover1 | 716:11b41f651697 | 21 | #include "GattAttribute.h" |
rgrover1 | 716:11b41f651697 | 22 | #include "ServiceDiscovery.h" |
rgrover1 | 716:11b41f651697 | 23 | |
rgrover1 | 716:11b41f651697 | 24 | #include "GattCallbackParamTypes.h" |
rgrover1 | 716:11b41f651697 | 25 | |
rgrover1 | 716:11b41f651697 | 26 | class GattClient { |
rgrover1 | 716:11b41f651697 | 27 | public: |
rgrover1 | 716:11b41f651697 | 28 | typedef void (*ReadCallback_t)(const GattReadCallbackParams *params); |
rgrover1 | 716:11b41f651697 | 29 | |
rgrover1 | 716:11b41f651697 | 30 | enum WriteOp_t { |
rgrover1 | 719:5f5c3812ea8f | 31 | GATT_OP_WRITE_REQ = 0x01, /**< Write Request. */ |
rgrover1 | 719:5f5c3812ea8f | 32 | GATT_OP_WRITE_CMD = 0x02, /**< Write Command. */ |
rgrover1 | 716:11b41f651697 | 33 | }; |
rgrover1 | 716:11b41f651697 | 34 | |
rgrover1 | 716:11b41f651697 | 35 | typedef void (*WriteCallback_t)(const GattWriteCallbackParams *params); |
rgrover1 | 716:11b41f651697 | 36 | |
rgrover1 | 716:11b41f651697 | 37 | /* |
rgrover1 | 716:11b41f651697 | 38 | * The following functions are meant to be overridden in the platform-specific sub-class. |
rgrover1 | 716:11b41f651697 | 39 | */ |
rgrover1 | 716:11b41f651697 | 40 | public: |
rgrover1 | 716:11b41f651697 | 41 | /** |
rgrover1 | 719:5f5c3812ea8f | 42 | * Launch service discovery. Once launched, application callbacks will be |
rgrover1 | 719:5f5c3812ea8f | 43 | * invoked for matching services/characteristics. isServiceDiscoveryActive() |
rgrover1 | 719:5f5c3812ea8f | 44 | * can be used to determine status; and a termination callback (if setup) |
rgrover1 | 719:5f5c3812ea8f | 45 | * will be invoked at the end. Service discovery can be terminated prematurely |
rgrover1 | 719:5f5c3812ea8f | 46 | * if needed using terminateServiceDiscovery(). |
rgrover1 | 716:11b41f651697 | 47 | * |
rgrover1 | 716:11b41f651697 | 48 | * @param connectionHandle |
rgrover1 | 716:11b41f651697 | 49 | * Handle for the connection with the peer. |
rgrover1 | 716:11b41f651697 | 50 | * @param sc |
rgrover1 | 716:11b41f651697 | 51 | * This is the application callback for matching service. Taken as |
rgrover1 | 716:11b41f651697 | 52 | * NULL by default. Note: service discovery may still be active |
rgrover1 | 716:11b41f651697 | 53 | * when this callback is issued; calling asynchronous BLE-stack |
rgrover1 | 716:11b41f651697 | 54 | * APIs from within this application callback might cause the |
rgrover1 | 716:11b41f651697 | 55 | * stack to abort service discovery. If this becomes an issue, it |
rgrover1 | 716:11b41f651697 | 56 | * may be better to make local copy of the discoveredService and |
rgrover1 | 716:11b41f651697 | 57 | * wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 58 | * service. |
rgrover1 | 716:11b41f651697 | 59 | * @param cc |
rgrover1 | 716:11b41f651697 | 60 | * This is the application callback for matching characteristic. |
rgrover1 | 716:11b41f651697 | 61 | * Taken as NULL by default. Note: service discovery may still be |
rgrover1 | 716:11b41f651697 | 62 | * active when this callback is issued; calling asynchronous |
rgrover1 | 716:11b41f651697 | 63 | * BLE-stack APIs from within this application callback might cause |
rgrover1 | 716:11b41f651697 | 64 | * the stack to abort service discovery. If this becomes an issue, |
rgrover1 | 716:11b41f651697 | 65 | * it may be better to make local copy of the discoveredCharacteristic |
rgrover1 | 716:11b41f651697 | 66 | * and wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 67 | * characteristic. |
rgrover1 | 716:11b41f651697 | 68 | * @param matchingServiceUUID |
rgrover1 | 716:11b41f651697 | 69 | * UUID based filter for specifying a service in which the application is |
rgrover1 | 716:11b41f651697 | 70 | * interested. By default it is set as the wildcard UUID_UNKNOWN, |
rgrover1 | 716:11b41f651697 | 71 | * in which case it matches all services. If characteristic-UUID |
rgrover1 | 716:11b41f651697 | 72 | * filter (below) is set to the wildcard value, then a service |
rgrover1 | 716:11b41f651697 | 73 | * callback will be invoked for the matching service (or for every |
rgrover1 | 716:11b41f651697 | 74 | * service if the service filter is a wildcard). |
rgrover1 | 716:11b41f651697 | 75 | * @param matchingCharacteristicUUIDIn |
rgrover1 | 716:11b41f651697 | 76 | * UUID based filter for specifying characteristic in which the application |
rgrover1 | 716:11b41f651697 | 77 | * is interested. By default it is set as the wildcard UUID_UKNOWN |
rgrover1 | 716:11b41f651697 | 78 | * to match against any characteristic. If both service-UUID |
rgrover1 | 716:11b41f651697 | 79 | * filter and characteristic-UUID filter are used with non- wildcard |
rgrover1 | 716:11b41f651697 | 80 | * values, then only a single characteristic callback is |
rgrover1 | 716:11b41f651697 | 81 | * invoked for the matching characteristic. |
rgrover1 | 716:11b41f651697 | 82 | * |
rgrover1 | 716:11b41f651697 | 83 | * @note Using wildcard values for both service-UUID and characteristic- |
rgrover1 | 716:11b41f651697 | 84 | * UUID will result in complete service discovery--callbacks being |
rgrover1 | 716:11b41f651697 | 85 | * called for every service and characteristic. |
rgrover1 | 716:11b41f651697 | 86 | * |
rgrover1 | 716:11b41f651697 | 87 | * @note Providing NULL for the characteristic callback will result in |
rgrover1 | 716:11b41f651697 | 88 | * characteristic discovery being skipped for each matching |
rgrover1 | 716:11b41f651697 | 89 | * service. This allows for an inexpensive method to discover only |
rgrover1 | 716:11b41f651697 | 90 | * services. |
rgrover1 | 716:11b41f651697 | 91 | * |
rgrover1 | 716:11b41f651697 | 92 | * @return |
rgrover1 | 716:11b41f651697 | 93 | * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. |
rgrover1 | 716:11b41f651697 | 94 | */ |
rgrover1 | 716:11b41f651697 | 95 | virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle, |
rgrover1 | 716:11b41f651697 | 96 | ServiceDiscovery::ServiceCallback_t sc = NULL, |
rgrover1 | 716:11b41f651697 | 97 | ServiceDiscovery::CharacteristicCallback_t cc = NULL, |
rgrover1 | 716:11b41f651697 | 98 | const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), |
rgrover1 | 716:11b41f651697 | 99 | const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { |
rgrover1 | 725:f4a355b35cf8 | 100 | return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 101 | } |
rgrover1 | 716:11b41f651697 | 102 | |
rgrover1 | 716:11b41f651697 | 103 | /** |
rgrover1 | 716:11b41f651697 | 104 | * Launch service discovery for services. Once launched, service discovery will remain |
rgrover1 | 716:11b41f651697 | 105 | * active with service-callbacks being issued back into the application for matching |
rgrover1 | 716:11b41f651697 | 106 | * services. isServiceDiscoveryActive() can be used to |
rgrover1 | 716:11b41f651697 | 107 | * determine status; and a termination callback (if setup) will be invoked |
rgrover1 | 716:11b41f651697 | 108 | * at the end. Service discovery can be terminated prematurely if needed |
rgrover1 | 716:11b41f651697 | 109 | * using terminateServiceDiscovery(). |
rgrover1 | 716:11b41f651697 | 110 | * |
rgrover1 | 716:11b41f651697 | 111 | * @param connectionHandle |
rgrover1 | 716:11b41f651697 | 112 | * Handle for the connection with the peer. |
rgrover1 | 716:11b41f651697 | 113 | * @param sc |
rgrover1 | 716:11b41f651697 | 114 | * This is the application callback for matching service. Note: service discovery may still be active |
rgrover1 | 716:11b41f651697 | 115 | * when this callback is issued; calling asynchronous BLE-stack |
rgrover1 | 716:11b41f651697 | 116 | * APIs from within this application callback might cause the |
rgrover1 | 716:11b41f651697 | 117 | * stack to abort service discovery. If this becomes an issue, it |
rgrover1 | 716:11b41f651697 | 118 | * may be better to make local copy of the discoveredService and |
rgrover1 | 716:11b41f651697 | 119 | * wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 120 | * service. |
rgrover1 | 716:11b41f651697 | 121 | * @param matchingServiceUUID |
rgrover1 | 716:11b41f651697 | 122 | * UUID based filter for specifying a service in which the application is |
rgrover1 | 716:11b41f651697 | 123 | * interested. By default it is set as the wildcard UUID_UNKNOWN, |
rgrover1 | 716:11b41f651697 | 124 | * in which case it matches all services. |
rgrover1 | 716:11b41f651697 | 125 | * |
rgrover1 | 716:11b41f651697 | 126 | * @return |
rgrover1 | 716:11b41f651697 | 127 | * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. |
rgrover1 | 716:11b41f651697 | 128 | */ |
rgrover1 | 716:11b41f651697 | 129 | virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, |
rgrover1 | 716:11b41f651697 | 130 | ServiceDiscovery::ServiceCallback_t callback, |
rgrover1 | 716:11b41f651697 | 131 | const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { |
rgrover1 | 725:f4a355b35cf8 | 132 | return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 133 | } |
rgrover1 | 716:11b41f651697 | 134 | |
rgrover1 | 716:11b41f651697 | 135 | /** |
rgrover1 | 716:11b41f651697 | 136 | * Launch service discovery for services. Once launched, service discovery will remain |
rgrover1 | 716:11b41f651697 | 137 | * active with service-callbacks being issued back into the application for matching |
rgrover1 | 716:11b41f651697 | 138 | * services. isServiceDiscoveryActive() can be used to |
rgrover1 | 716:11b41f651697 | 139 | * determine status; and a termination callback (if setup) will be invoked |
rgrover1 | 716:11b41f651697 | 140 | * at the end. Service discovery can be terminated prematurely if needed |
rgrover1 | 716:11b41f651697 | 141 | * using terminateServiceDiscovery(). |
rgrover1 | 716:11b41f651697 | 142 | * |
rgrover1 | 716:11b41f651697 | 143 | * @param connectionHandle |
rgrover1 | 716:11b41f651697 | 144 | * Handle for the connection with the peer. |
rgrover1 | 716:11b41f651697 | 145 | * @param sc |
rgrover1 | 716:11b41f651697 | 146 | * This is the application callback for matching service. Note: service discovery may still be active |
rgrover1 | 716:11b41f651697 | 147 | * when this callback is issued; calling asynchronous BLE-stack |
rgrover1 | 716:11b41f651697 | 148 | * APIs from within this application callback might cause the |
rgrover1 | 716:11b41f651697 | 149 | * stack to abort service discovery. If this becomes an issue, it |
rgrover1 | 716:11b41f651697 | 150 | * may be better to make local copy of the discoveredService and |
rgrover1 | 716:11b41f651697 | 151 | * wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 152 | * service. |
rgrover1 | 716:11b41f651697 | 153 | * @param startHandle, endHandle |
rgrover1 | 716:11b41f651697 | 154 | * Handle range within which to limit the search |
rgrover1 | 716:11b41f651697 | 155 | * |
rgrover1 | 716:11b41f651697 | 156 | * @return |
rgrover1 | 716:11b41f651697 | 157 | * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. |
rgrover1 | 716:11b41f651697 | 158 | */ |
rgrover1 | 716:11b41f651697 | 159 | virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, |
rgrover1 | 716:11b41f651697 | 160 | ServiceDiscovery::ServiceCallback_t callback, |
rgrover1 | 716:11b41f651697 | 161 | GattAttribute::Handle_t startHandle, |
rgrover1 | 716:11b41f651697 | 162 | GattAttribute::Handle_t endHandle) { |
rgrover1 | 725:f4a355b35cf8 | 163 | return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 164 | } |
rgrover1 | 716:11b41f651697 | 165 | |
rgrover1 | 716:11b41f651697 | 166 | /** |
rgrover1 | 716:11b41f651697 | 167 | * Is service-discovery currently active? |
rgrover1 | 716:11b41f651697 | 168 | */ |
rgrover1 | 716:11b41f651697 | 169 | virtual bool isServiceDiscoveryActive(void) const { |
rgrover1 | 716:11b41f651697 | 170 | return false; /* default implementation; override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 171 | } |
rgrover1 | 716:11b41f651697 | 172 | |
rgrover1 | 716:11b41f651697 | 173 | /** |
rgrover1 | 716:11b41f651697 | 174 | * Terminate an ongoing service-discovery. This should result in an |
rgrover1 | 716:11b41f651697 | 175 | * invocation of the TerminationCallback if service-discovery is active. |
rgrover1 | 716:11b41f651697 | 176 | */ |
rgrover1 | 716:11b41f651697 | 177 | virtual void terminateServiceDiscovery(void) { |
rgrover1 | 716:11b41f651697 | 178 | /* default implementation; override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 179 | } |
rgrover1 | 716:11b41f651697 | 180 | |
rgrover1 | 716:11b41f651697 | 181 | /* Initiate a Gatt Client read procedure by attribute-handle. */ |
rgrover1 | 716:11b41f651697 | 182 | virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const { |
rgrover1 | 725:f4a355b35cf8 | 183 | return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 184 | } |
rgrover1 | 716:11b41f651697 | 185 | |
rgrover1 | 716:11b41f651697 | 186 | /** |
rgrover1 | 716:11b41f651697 | 187 | * Initiate a GATT Client write procedure. |
rgrover1 | 716:11b41f651697 | 188 | * |
rgrover1 | 716:11b41f651697 | 189 | * @param[in] cmd |
rgrover1 | 716:11b41f651697 | 190 | * Command can be either a write-request (which generates a |
rgrover1 | 716:11b41f651697 | 191 | * matching response from the peripheral), or a write-command, |
rgrover1 | 716:11b41f651697 | 192 | * which doesn't require the connected peer to respond. |
rgrover1 | 716:11b41f651697 | 193 | * @param[in] connHandle |
rgrover1 | 716:11b41f651697 | 194 | * Connection handle. |
rgrover1 | 716:11b41f651697 | 195 | * @param[in] attributeHandle |
rgrover1 | 716:11b41f651697 | 196 | * handle for the target attribtue on the remote GATT server. |
rgrover1 | 716:11b41f651697 | 197 | * @param[in] length |
rgrover1 | 716:11b41f651697 | 198 | * length of the new value. |
rgrover1 | 716:11b41f651697 | 199 | * @param[in] value |
rgrover1 | 716:11b41f651697 | 200 | * new value being written. |
rgrover1 | 716:11b41f651697 | 201 | */ |
rgrover1 | 716:11b41f651697 | 202 | virtual ble_error_t write(GattClient::WriteOp_t cmd, |
rgrover1 | 716:11b41f651697 | 203 | Gap::Handle_t connHandle, |
rgrover1 | 716:11b41f651697 | 204 | GattAttribute::Handle_t attributeHandle, |
rgrover1 | 716:11b41f651697 | 205 | size_t length, |
rgrover1 | 716:11b41f651697 | 206 | const uint8_t *value) const { |
rgrover1 | 725:f4a355b35cf8 | 207 | return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 208 | } |
rgrover1 | 716:11b41f651697 | 209 | |
rgrover1 | 720:ce8a760a4504 | 210 | /* Event callback handlers. */ |
rgrover1 | 720:ce8a760a4504 | 211 | public: |
rgrover1 | 720:ce8a760a4504 | 212 | /** |
rgrover1 | 720:ce8a760a4504 | 213 | * Setup a callback for read response events. |
rgrover1 | 720:ce8a760a4504 | 214 | */ |
rgrover1 | 720:ce8a760a4504 | 215 | void onDataRead(ReadCallback_t callback) { |
rgrover1 | 720:ce8a760a4504 | 216 | onDataReadCallback = callback; |
rgrover1 | 720:ce8a760a4504 | 217 | } |
rgrover1 | 720:ce8a760a4504 | 218 | |
rgrover1 | 720:ce8a760a4504 | 219 | /** |
rgrover1 | 720:ce8a760a4504 | 220 | * Setup a callback for write response events. |
rgrover1 | 720:ce8a760a4504 | 221 | * @Note: write commands (issued using writeWoResponse) don't generate a response. |
rgrover1 | 720:ce8a760a4504 | 222 | */ |
rgrover1 | 720:ce8a760a4504 | 223 | void onDataWrite(WriteCallback_t callback) { |
rgrover1 | 720:ce8a760a4504 | 224 | onDataWriteCallback = callback; |
rgrover1 | 720:ce8a760a4504 | 225 | } |
rgrover1 | 720:ce8a760a4504 | 226 | |
rgrover1 | 716:11b41f651697 | 227 | /** |
rgrover1 | 716:11b41f651697 | 228 | * Setup callback for when serviceDiscovery terminates. |
rgrover1 | 716:11b41f651697 | 229 | */ |
rgrover1 | 716:11b41f651697 | 230 | virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) { |
rgrover1 | 716:11b41f651697 | 231 | /* default implementation; override this API if this capability is supported. */ |
rgrover1 | 716:11b41f651697 | 232 | } |
rgrover1 | 716:11b41f651697 | 233 | |
rgrover1 | 716:11b41f651697 | 234 | protected: |
rgrover1 | 716:11b41f651697 | 235 | GattClient() { |
rgrover1 | 716:11b41f651697 | 236 | /* empty */ |
rgrover1 | 716:11b41f651697 | 237 | } |
rgrover1 | 716:11b41f651697 | 238 | |
rgrover1 | 720:ce8a760a4504 | 239 | /* Entry points for the underlying stack to report events back to the user. */ |
rgrover1 | 720:ce8a760a4504 | 240 | public: |
rgrover1 | 720:ce8a760a4504 | 241 | void processReadResponse(const GattReadCallbackParams *params) { |
rgrover1 | 720:ce8a760a4504 | 242 | if (onDataReadCallback) { |
rgrover1 | 720:ce8a760a4504 | 243 | onDataReadCallback(params); |
rgrover1 | 720:ce8a760a4504 | 244 | } |
rgrover1 | 720:ce8a760a4504 | 245 | } |
rgrover1 | 720:ce8a760a4504 | 246 | |
rgrover1 | 720:ce8a760a4504 | 247 | void processWriteResponse(const GattWriteCallbackParams *params) { |
rgrover1 | 720:ce8a760a4504 | 248 | if (onDataWriteCallback) { |
rgrover1 | 720:ce8a760a4504 | 249 | onDataWriteCallback(params); |
rgrover1 | 720:ce8a760a4504 | 250 | } |
rgrover1 | 720:ce8a760a4504 | 251 | } |
rgrover1 | 720:ce8a760a4504 | 252 | |
rgrover1 | 720:ce8a760a4504 | 253 | protected: |
rgrover1 | 720:ce8a760a4504 | 254 | ReadCallback_t onDataReadCallback; |
rgrover1 | 720:ce8a760a4504 | 255 | WriteCallback_t onDataWriteCallback; |
rgrover1 | 720:ce8a760a4504 | 256 | |
rgrover1 | 716:11b41f651697 | 257 | private: |
rgrover1 | 716:11b41f651697 | 258 | /* disallow copy and assignment */ |
rgrover1 | 716:11b41f651697 | 259 | GattClient(const GattClient &); |
rgrover1 | 716:11b41f651697 | 260 | GattClient& operator=(const GattClient &); |
rgrover1 | 716:11b41f651697 | 261 | }; |
rgrover1 | 716:11b41f651697 | 262 | |
rgrover1 | 716:11b41f651697 | 263 | #endif // ifndef __GATT_CLIENT_H__ |