gatt/GattCallbackParamTypes.h

/* 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__*/