Mbed OS Reference | GattCallbackParamTypes.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 #include "ble/common/CallChainOfFunctionPointersWithContext.h"
 
 #ifndef MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__
 #define MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__
 
 /**
  * @addtogroup ble
  * @{
  * @addtogroup gatt
  * @{
  */
 
 /**
  * GATT Write event definition.
  *
  * Instances of this type are created and passed to user registered callbacks
  * whether the GattServer has received a write request or a GattClient has
  * received a write response.
  *
  * @attention The GattServer only populates the fields offset, len and data
  * when it has received a write request. Callbacks attached to the GattClient
  * do not use those fields.
  *
  * @attention The GattClient only populates the fields status and error_code
  * when it has received a write response. Callbacks attached to the GattServer
  * do not use those fields.
  */
 struct GattWriteCallbackParams {
     /**
      * Enumeration of allowed write operations.
      */
     enum WriteOp_t {
         /**
          * Invalid operation.
          */
         OP_INVALID = 0x00,
 
         /**
          * 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,
     };
 
     /**
      * Handle of the connection that triggered the event.
      */
     ble::connection_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;
 
     union {
         /**
          * Offset within the attribute value to be written.
          *
          * @attention Reserved for GattServer registered callbacks.
          */
         uint16_t offset;
 
         /**
          * Status of the GattClient Write operation.
          *
          * @attention Reserved for GattClient registered callbacks.
          */
         ble_error_t status;
     };
 
     union {
         /**
          * Length (in bytes) of the data to write.
          *
          * @attention Reserved for GattServer registered callbacks.
          */
         uint16_t len;
 
         /**
          * Error code of the GattClient Write operation.
          *
          * @attention Reserved for GattClient registered callbacks.
          */
         uint8_t error_code;
     };
 
     /**
      * Pointer to the data to write.
      *
      * @attention Data may not persist beyond the callback scope.
      *
      * @attention Reserved for GattServer registered callbacks.
      */
     const uint8_t *data;
 };
 
 /**
  * GATT Read event definition.
  *
  * Instances of this type are created and passed to user registered callbacks
  * whether the GattServer has received a read request or a GattClient has
  * received a read response.
  *
  * @attention The GattClient only populates the fields status and error_code
  * when it has received a read response. Callbacks attached to the GattServer
  * do not use those fields.
  */
 struct GattReadCallbackParams {
     /**
      * Handle of the connection that triggered the event.
      */
     ble::connection_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 {
         /**
          * Length in bytes of the data read.
          */
         uint16_t len;
 
         /**
          * Error code of the GattClient read operation.
          *
          * @attention Reserved for GattClient registered callbacks.
          *
          * @attention set if status is not equal to BLE_ERROR_NONE; otherwise,
          * this field is interpreted as len.
          */
         uint8_t error_code;
     };
 
     /**
      * Pointer to the data read.
      *
      * @attention Data may not persist beyond the callback scope.
      */
     const uint8_t *data;
 
     /**
      * Status of the GattClient Read operation.
      *
      * @attention 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 {
     /**
      * Success.
      */
     AUTH_CALLBACK_REPLY_SUCCESS = 0x00,
 
     /** The attribute handle given was not valid on this server. */
     AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x01,
 
     /** The attribute cannot be read. */
     AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x02,
 
     /** The attribute cannot be written. */
     AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x03,
 
     /** The attribute PDU was invalid. */
     AUTH_CALLBACK_REPLY_ATTERR_INVALID_PDU = 0x04,
 
     /** The attribute requires authentication before it can be read or
      * written.
      */
     AUTH_CALLBACK_REPLY_ATTERR_INSUFFICIENT_AUTHENTICATION = 0x05,
     AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x05,
 
     /** Attribute server does not support the request received from the
      * client.
      */
     AUTH_CALLBACK_REPLY_ATTERR_REQUEST_NOT_SUPPORTED = 0x06,
 
     /** Offset specified was past the end of the attribute. */
     AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x07,
 
     /** The attribute requires authorization before it can be read or written. */
     AUTH_CALLBACK_REPLY_ATTERR_INSUFFICIENT_AUTHORIZATION = 0x08,
     AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x08,
 
     /** Too many prepare writes have been queued. */
     AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x09,
 
     /** No attribute found within the given attribute handle range. */
     AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x0A,
 
     /** The attribute cannot be read using the Read Blob Request. */
     AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x0B,
 
     /** The Encryption Key Size used for encrypting this link is
      * insufficient.
      */
     AUTH_CALLBACK_REPLY_ATTERR_INSUFFICIENT_ENCRYPTION_KEY_SIZE = 0x0C,
 
     /** The attribute value length is invalid for the operation. */
     AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATTRIBUTE_VALUE_LENGTH = 0x0D,
     AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x0D,
 
     /** The attribute request that was requested has encountered an error
      * that was unlikely, and therefore could not be completed as requested.
      */
     AUTH_CALLBACK_REPLY_ATTERR_UNLIKELY_ERROR = 0x0E,
 
     /** The attribute requires encryption before it can be read or written. */
     AUTH_CALLBACK_REPLY_ATTERR_INSUFFICIENT_ENCRYPTION = 0x0F,
 
     /** The attribute type is not a supported grouping attribute as defined
      * by a higher layer specification.
      */
     AUTH_CALLBACK_REPLY_ATTERR_UNSUPPORTED_GROUP_TYPE = 0x10,
 
     /** Insufficient Resources to complete the request. */
     AUTH_CALLBACK_REPLY_ATTERR_INSUFFICIENT_RESOURCES = 0x11,
     AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x11,
 
     /* 0x12 - 0x7F => reserved for future use */
 
     /* 0x80 - 0x9F => Application Error */
 
     /* 0xA0 0xDF => Reserved for future use */
 
     /* 0xE0 - 0xFF Common Profile and service Error Codes */
 
     /** The Write Request Rejected error code is used when a requested write
      * operation cannot be fulfilled for reasons other than permissions.
      */
     AUTH_CALLBACK_REPLY_ATTERR_WRITE_REQUEST_REJECTED = 0xFC,
 
     /** The Client Characteristic Configuration Descriptor Improperly
      * Configured error code is used when a Client Characteristic
      * Configuration descriptor is not configured according to the
      * requirements of the profile or service.
      */
     AUTH_CALLBACK_REPLY_ATTERR_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR_IMPROPERLY_CONFIGURED = 0xFD,
 
     /** The Procedure Already in Progress error code is used when a profile
      * or service request cannot be serviced because an operation that has
      * been previously triggered is still in progress
      */
     AUTH_CALLBACK_REPLY_ATTERR_PROCEDURE_ALREADY_IN_PROGRESS = 0xFE,
 
     /** The Out of Range error code is used when an attribute value is out
      * of range as defined by a profile or service specification.
      */
     AUTH_CALLBACK_REPLY_ATTERR_OUT_OF_RANGE = 0xFF,
 };
 
 /**
  * GATT write authorization request event.
  */
 struct GattWriteAuthCallbackParams {
     /**
      * Handle of the connection that triggered the event.
      */
     ble::connection_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.
      *
      * The callback sets this parameter. If the value is set to
      * AUTH_CALLBACK_REPLY_SUCCESS, then the write request is accepted;
      * otherwise, an error code is returned to the peer client.
      */
     GattAuthCallbackReply_t authorizationReply;
 };
 
 /**
  * GATT read authorization request event.
  */
 struct GattReadAuthCallbackParams {
     /**
      * The handle of the connection that triggered the event.
      */
     ble::connection_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.
      *
      * The callback sets this parameter. If the value is set to
      * AUTH_CALLBACK_REPLY_SUCCESS, then the read request is accepted;
      * otherwise, an error code is returned to the peer client.
      */
     GattAuthCallbackReply_t authorizationReply;
 };
 
 /**
  * Handle Value Notification/Indication event.
  *
  * The GattClient generates this type of event upon the reception of a
  * Handle Value Notification or Indication.
  *
  * The event is passed to callbacks registered by GattClient::onHVX().
  */
 struct GattHVXCallbackParams {
     /**
      * The handle of the connection that triggered the event.
      */
     ble::connection_handle_t connHandle;
 
     /**
      * 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;
 
 };
 
 /**
  * Gatt Data Sent Attribute related events
  *
  * Used by `onDataSent`
  */
 struct GattDataSentCallbackParams {
 
     /**
      * The handle of the connection that triggered the event.
      */
     ble::connection_handle_t connHandle;
 
     /**
      * Attribute Handle to which the event applies
      */
     GattAttribute::Handle_t attHandle;
 
 };
 
 /**
  * Gatt Updates Changed Attribute related events
  *
  * Used by `onUpdatesEnabled` and 'onUpdatesDisabled'
  */
 struct GattUpdatesChangedCallbackParams {
 
     /**
      * The handle of the connection that triggered the event.
      */
     ble::connection_handle_t connHandle;
 
     /**
      * The handle of the CCCD producing the event
      */
     GattAttribute::Handle_t attHandle;
 
     /**
      * The value handle of the characteristic containing the CCCD  
      */
     GattAttribute::Handle_t charHandle;
     
 };
 
 using GattUpdatesEnabledCallbackParams       = GattUpdatesChangedCallbackParams;
 using GattUpdatesDisabledCallbackParams      = GattUpdatesChangedCallbackParams;
 using GattConfirmationReceivedCallbackParams = GattDataSentCallbackParams;
 
 namespace ble {
 
 /**
  * Attribute read event handler.
  *
  * @see GattClient::onDataRead().
  */
 typedef FunctionPointerWithContext<const GattReadCallbackParams *> ReadCallback_t;
 
 /**
  * Callchain of attribute read event handlers.
  */
 typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> ReadCallbackChain_t;
 
 /**
  * Attribute write event handler.
  *
  * @see GattClient::onDataWrite().
  */
 typedef FunctionPointerWithContext<const GattWriteCallbackParams *> WriteCallback_t;
 
 /**
  * Callchain of attribute write event handlers.
  *
  * @see GattClient::onDataWrite().
  */
 typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> WriteCallbackChain_t;
 
 }
 
 /**
  * @}
  * @}
  * @}
  */
 
 #endif /*MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__*/
Important Information for this Arm website
