ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BLE: Improve GattCallbackParamTypes.h documentation.

pull/5392/head
Vincent Coubard 2017-10-24 17:08:47 -05:00
parent e3252da515
commit a7b4d6accd
1 changed files with 331 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

394
features/FEATURE_BLE/ble/GattCallbackParamTypes.h
View File

@ -14,139 +14,377 @@
* limitations under the License. * limitations under the License.
*/ */
#ifndef __GATT_CALLBACK_PARAM_TYPES_H__ #ifndef MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__
#define __GATT_CALLBACK_PARAM_TYPES_H__ #define MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__
/** /**
* Parameter of the callback invoked on a write operation. * @addtogroup ble
* This parameter is used whether a GattServer as received a write operation or * @{
* if the GattClient has completed a write operation. * @addtogroup gatt
* @{
*/
/**
* GATT Write event definition.
* *
* @important The fields connHandle, handle and writeOp are used in both * Instances of this type are created and passed to user registered callbacks
* callbacks while: * whether the GattServer has received a write request or a GattClient has
* - offset, len and data are reserved for GattServer write callbacks. * received a write response.
* - status and error_code are reserved for GattClient write callbacks. *
* @important The fields offset, len and data are only populated by the
* GattServer when it receive a write request. Those fields shall not be used
* by callbacks attached to the GattClient.
*
* @important The fields status and error_code are only populated by the
* GattClient when it has received a write response. Those fields shall not be
* used by callbacks attached to the GattServer.
*/ */
struct GattWriteCallbackParams { struct GattWriteCallbackParams {
/** /**
* Enumeration for write operations. * Enumeration of allowed write operations.
*/ */
enum WriteOp_t { enum WriteOp_t {
OP_INVALID = 0x00, /**< Invalid operation. */ /**
OP_WRITE_REQ = 0x01, /**< Write request. */ * Invalid operation.
OP_WRITE_CMD = 0x02, /**< Write command. */ */
OP_SIGN_WRITE_CMD = 0x03, /**< Signed write command. */ OP_INVALID = 0x00,
OP_PREP_WRITE_REQ = 0x04, /**< Prepare write request. */
OP_EXEC_WRITE_REQ_CANCEL = 0x05, /**< Execute write request: cancel all prepared writes. */ /**
OP_EXEC_WRITE_REQ_NOW = 0x06, /**< Execute write request: immediately execute all prepared writes. */ * Write request.
*/
OP_WRITE_REQ = 0x01,
/**
* Write command.
*/
OP_WRITE_CMD = 0x02,
/**
* Signed write command.
*/
OP_SIGN_WRITE_CMD = 0x03,
/**
* Prepare write request.
*/
OP_PREP_WRITE_REQ = 0x04,
/**
* Execute write request: cancel all prepared writes.
*/
OP_EXEC_WRITE_REQ_CANCEL = 0x05,
/**
* Execute write request: immediately execute all prepared writes.
*/
OP_EXEC_WRITE_REQ_NOW = 0x06,
}; };
Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ /**
GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */ * Handle of the connection that triggered the event.
WriteOp_t writeOp; /**< Type of write operation. */ */
Gap::Handle_t connHandle;
/**
* Handle of the attribute to which the write operation applies.
*/
GattAttribute::Handle_t handle;
/**
* Type of the write operation.
*/
WriteOp_t writeOp;
// Note: offset is used in GattServer while status is used in GattClient
union { union {
uint16_t offset; /**< Offset for the GattServer write operation. */ /**
ble_error_t status; /**< Status of the GattClient Write operation */ * Offset within the attribute value to be written.
*
* @important Reserved for GattServer registered callbacks.
*/
uint16_t offset;
/**
* Status of the GattClient Write operation
*
* @important Reserved for GattClient registered callbacks.
*/
ble_error_t status;
}; };
// Note: len is used in GattServer while error_code is used in GattClient
union { union {
uint16_t len; /**< Length (in bytes) of the data to write (GattServer). */ /**
uint8_t error_code; /**< Error code of the GattClient Write operation */ * Length (in bytes) of the data to write.
*
* @important Reserved for GattServer registered callbacks.
*/
uint16_t len;
/**
* Error code of the GattClient Write operation.
*
* @important Reserved for GattClient registered callbacks.
*/
uint8_t error_code;
}; };
/** /**
* Pointer to the data to write. * Pointer to the data to write.
* *
* @note Data might not persist beyond the callback; make a local copy if * @important Data may not persist beyond the callback scope.
* needed. *
* @note This field is not used by callbacks invoked by the GattClient module. * @important Reserved for GattServer registered callbacks.
*/ */
const uint8_t *data; const uint8_t *data;
}; };
/** /**
* Parameter of the callback invoked on a read operation. * GATT Read event definition.
* This parameter is used whether a GattServer as received a read operation or
* if the GattClient has completed a read operation.
* *
* @important The fields connHandle, handle and offset are used in both * Instances of this type are created and passed to user registered callbacks
* callbacks while: * whether the GattServer has received a read request or a GattClient has
* - len and data are reserved for GattServer read callbacks. * received a read response.
* - status and error_code are reserved for GattClient read callbacks. *
* @important The fields status and error_code are only populated by the
* GattClient when it has received a read response. Those fields shall not be
* used by callbacks attached to the GattServer.
*/ */
struct GattReadCallbackParams { struct GattReadCallbackParams {
Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ /**
GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */ * Handle of the connection that triggered the event.
uint16_t offset; /**< Offset for the read operation. */ */
Gap::Handle_t connHandle;
/**
* Attribute Handle to which the read operation applies.
*/
GattAttribute::Handle_t handle;
/**
* Offset within the attribute value read.
*/
uint16_t offset;
union { union {
uint16_t len; /**< Length (in bytes) of the data to read. */ /**
uint8_t error_code; /**< Error code if any (GattClient) */ * Length in bytes of the data read .
*/
uint16_t len;
/**
* Error code of the GattClient read operation.
*
* @important Reserved for GattClient registered callbacks.
*
* @important set if status is not equal to BLE_ERROR_NONE otherwise
* this field shall be interpreted as len.
*/
uint8_t error_code;
}; };
/** /**
* Pointer to the data read. * Pointer to the data read.
* *
* @note Data might not persist beyond the callback; make a local copy if * @important Data may not persist beyond the callback scope.
* needed.
*/ */
const uint8_t *data; const uint8_t *data;
ble_error_t status; /**< Status of the operation BLE_ERROR_NONE in case of success or the error in case of error */
/**
* Status of the GattClient Read operation
*
* @important Reserved for GattClient registered callbacks.
*/
ble_error_t status;
}; };
/**
* @addtogroup server
* @{
*/
/**
* Enumeration of allowed values returned by read or write authorization process.
*/
enum GattAuthCallbackReply_t { enum GattAuthCallbackReply_t {
AUTH_CALLBACK_REPLY_SUCCESS = 0x00, /**< Success. */ /**
AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101, /**< ATT Error: Invalid attribute handle. */ * Success.
AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x0102, /**< ATT Error: Read not permitted. */ */
AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x0103, /**< ATT Error: Write not permitted. */ AUTH_CALLBACK_REPLY_SUCCESS = 0x00,
AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x0105, /**< ATT Error: Authenticated link required. */
AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x0107, /**< ATT Error: The specified offset was past the end of the attribute. */ /**
AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108, /**< ATT Error: Used in ATT as "insufficient authorization". */ * ATT Error: Invalid attribute handle.
AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x0109, /**< ATT Error: Used in ATT as "prepare queue full". */ */
AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x010A, /**< ATT Error: Used in ATT as "attribute not found". */ AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101,
AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x010B, /**< ATT Error: Attribute cannot be read or written using read/write blob requests. */
AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x010D, /**< ATT Error: Invalid value size. */ /**
AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x0111, /**< ATT Error: Encrypted link required. */ * ATT Error: Read not permitted.
*/
AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x0102,
/**
* ATT Error: Write not permitted.
*/
AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x0103,
/**
* ATT Error: Authenticated link required.
*/
AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x0105,
/**
* ATT Error: The specified offset was past the end of the attribute.
*/
AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x0107,
/**
* ATT Error: Used in ATT as "insufficient authorization".
*/
AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108,
/**
* ATT Error: Used in ATT as "prepare queue full".
*/
AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x0109,
/**
* ATT Error: Used in ATT as "attribute not found".
*/
AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x010A,
/**
* ATT Error: Attribute cannot be read or written using read/write blob
* requests.
*/
AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x010B,
/**
* ATT Error: Invalid value size.
*/
AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x010D,
/**
* ATT Error: Encrypted link required.
*/
AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x0111,
}; };
/**
* GATT write authorization request event.
*/
struct GattWriteAuthCallbackParams { struct GattWriteAuthCallbackParams {
Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */
GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */
uint16_t offset; /**< Offset for the write operation. */
uint16_t len; /**< Length of the incoming data. */
const uint8_t *data; /**< Incoming data, variable length. */
/** /**
* This is the out parameter that the callback needs to set to * Handle of the connection that triggered the event.
* AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed. */
Gap::Handle_t connHandle;
/**
* Attribute Handle to which the write operation applies.
*/
GattAttribute::Handle_t handle;
/**
* Offset for the write operation.
*/
uint16_t offset;
/**
* Length of the incoming data.
*/
uint16_t len;
/**
* Incoming data.
*/
const uint8_t *data;
/**
* Authorization result.
*
* This parameter shall be set by the callback. If the value is set to
* AUTH_CALLBACK_REPLY_SUCCESS then the write request will be accepted
* otherwise an error code will be returned to the peer client.
*/ */
GattAuthCallbackReply_t authorizationReply; GattAuthCallbackReply_t authorizationReply;
}; };
/**
* GATT read authorization request event.
*/
struct GattReadAuthCallbackParams { struct GattReadAuthCallbackParams {
Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */
GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */
uint16_t offset; /**< Offset for the read operation. */
uint16_t len; /**< Optional: new length of the outgoing data. */
uint8_t *data; /**< Optional: new outgoing data. Leave at NULL if data is unchanged. */
/** /**
* This is the out parameter that the callback needs to set to * The handle of the connection that triggered the event.
* AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed. */
Gap::Handle_t connHandle;
/**
* Attribute Handle to which the read operation applies.
*/
GattAttribute::Handle_t handle;
/**
* Offset for the read operation.
*/
uint16_t offset;
/**
* Optional: new length of the outgoing data.
*/
uint16_t len;
/**
* Optional: new outgoing data. Leave at NULL if data is unchanged.
*/
uint8_t *data;
/**
* Authorization result.
*
* This parameter shall be set by the callback. If the value is set to
* AUTH_CALLBACK_REPLY_SUCCESS then the read request will be accepted
* otherwise an error code will be returned to the peer client.
*/ */
GattAuthCallbackReply_t authorizationReply; GattAuthCallbackReply_t authorizationReply;
}; };
/** /**
* For encapsulating handle-value update events (notifications or indications) * Handle Value Notification/Indication event.
* generated at the remote server. *
* This type of event is generated by the GattClient upon the reception of a
* Handle Value Notification or Indication.
*
* The event is passed to callbacks registered by GattClient::onHVX().
*/ */
struct GattHVXCallbackParams { struct GattHVXCallbackParams {
Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ /**
GattAttribute::Handle_t handle; /**< Attribute Handle to which the HVx operation applies. */ * The handle of the connection that triggered the event.
HVXType_t type; /**< Indication or Notification, see HVXType_t. */ */
uint16_t len; /**< Attribute data length. */ Gap::Handle_t connHandle;
const uint8_t *data; /**< Attribute data, variable length. */
/**
* Attribute Handle to which the HVx operation applies.
*/
GattAttribute::Handle_t handle;
/**
* Indication or Notification, see HVXType_t.
*/
HVXType_t type;
/**
* Attribute value length.
*/
uint16_t len;
/**
* Attribute value.
*/
const uint8_t *data;
}; };
#endif /*__GATT_CALLBACK_PARAM_TYPES_H__*/ /**
* @}
* @}
* @}
*/
#endif /*MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__*/