<commit_before>/* mbed Microcontroller Library
 * Copyright (c) 2006-2013 ARM Limited
 *
 * 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.
 */

#ifndef __GATT_CALLBACK_PARAM_TYPES_H__
#define __GATT_CALLBACK_PARAM_TYPES_H__

/**
 * Parameter of the callback invoked on a write operation.
 * This parameter is used whether a GattServer as received a write operation or
 * if the GattClient has completed a write operation.
 *
 * @important The fields connHandle, handle and writeOp are used in both
 * callbacks while:
 *   - offset, len and data are reserved for GattServer write callbacks.
 *   - status and error_code are reserved for GattClient write callbacks.
 */
struct GattWriteCallbackParams {
    /**
     * Enumeration for write operations.
     */
    enum WriteOp_t {
        OP_INVALID               = 0x00,  /**< Invalid operation. */
        OP_WRITE_REQ             = 0x01,  /**< Write request. */
        OP_WRITE_CMD             = 0x02,  /**< Write command. */
        OP_SIGN_WRITE_CMD        = 0x03,  /**< Signed write command. */
        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. */
    };

    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. */
    WriteOp_t                writeOp;    /**< Type of write operation. */

    // Note: offset is used in GattServer while status is used in GattClient
    union {
        uint16_t                offset;     /**< Offset for the GattServer write operation. */
        ble_error_t             status;     /**< Status of the GattClient Write operation */
    };

    // Note: len is used in GattServer while error_code is used in GattClient
    union {
        uint16_t                 len;        /**< Length (in bytes) of the data to write (GattServer). */
        uint8_t                  error_code; /**< Error code of the GattClient Write operation */
    };

    /**
     * Pointer to the data to write.
     *
     * @note Data might not persist beyond the callback; make a local copy if
     *       needed.
     * @note This field is not used by callbacks invoked by the GattClient module.
     */
    const uint8_t           *data;
};

/**
 * Parameter of the callback invoked on a read operation.
 * 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
 * callbacks while:
 *   - len and data are reserved for GattServer read callbacks.
 *   - status and error_code are reserved for GattClient read callbacks.
 */
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. */
    uint16_t                 offset;     /**< Offset for the read operation. */
    union {
        uint16_t             len;        /**< Length (in bytes) of the data to read. */
        uint8_t              error_code; /**< Error code if any (GattClient) */
    };

    /**
     * Pointer to the data read.
     *
     * @note Data might not persist beyond the callback; make a local copy if
     *       needed.
     */
    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 */
};

enum GattAuthCallbackReply_t {
    AUTH_CALLBACK_REPLY_SUCCESS                       = 0x00,    /**< Success. */
    AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE         = 0x0101,  /**< ATT Error: Invalid attribute handle. */
    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_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". */
    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_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. */
};

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
     * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed.
     */
    GattAuthCallbackReply_t  authorizationReply;
};

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
     * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed.
     */
    GattAuthCallbackReply_t  authorizationReply;
};

/**
 * For encapsulating handle-value update events (notifications or indications)
 * generated at the remote server.
 */
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. */
  HVXType_t                type;       /**< Indication or Notification, see HVXType_t. */
  uint16_t                 len;        /**< Attribute data length. */
  const uint8_t           *data;       /**< Attribute data, variable length. */
};

#endif /*__GATT_CALLBACK_PARAM_TYPES_H__*/
<commit_msg>BLE: Improve GattCallbackParamTypes.h documentation.<commit_after>/* mbed Microcontroller Library
 * Copyright (c) 2006-2013 ARM Limited
 *
 * 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.
 */

#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.
 *
 * @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 {
    /**
     * 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.
     */
    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;

    union {
        /**
         * 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;
    };

    union {
        /**
         * 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.
     *
     * @important Data may not persist beyond the callback scope.
     *
     * @important 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.
 *
 * @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 {
    /**
     * Handle of the connection that triggered the event.
     */
    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 {
        /**
         * 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.
     *
     * @important Data may not persist beyond the callback scope.
     */
    const uint8_t *data;

    /**
     * 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 {
    /**
     * Success.
     */
    AUTH_CALLBACK_REPLY_SUCCESS = 0x00,

    /**
     * ATT Error: Invalid attribute handle.
     */
    AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101,

    /**
     * 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 {
    /**
     * Handle of the connection that triggered the event.
     */
    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;
};

/**
 * GATT read authorization request event.
 */
struct GattReadAuthCallbackParams {
    /**
     * The handle of the connection that triggered the event.
     */
    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;
};

/**
 * Handle Value Notification/Indication event.
 *
 * 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 {
    /**
     * The handle of the connection that triggered the event.
     */
    Gap::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;

};

/**
 * @}
 * @}
 * @}
 */

#endif /*MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__*/

{'fraction_non_alphanumeric': 0.08194899391670567, 'fraction_numerical': 0.013219466541881142, 'mean_word_length': 2.3120883378535453, 'pattern_counts': {'":': 0, '<': 50, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6881956', 'n_tokens_mistral': 5081, 'n_tokens_neox': 4861, 'n_words': 1673}