diff --git a/bits_button.c b/bits_button.c index 4d8b37d..bce2cf1 100644 --- a/bits_button.c +++ b/bits_button.c @@ -404,7 +404,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) if (config == NULL) { - return -2; + return BITS_BTN_ERR_INVALID_PARAM; } debug_printf = config->bits_btn_debug_printf; @@ -416,14 +416,14 @@ int32_t bits_button_init(const bits_btn_config_t *config) { if(debug_printf) debug_printf("Invalid init parameters !\n"); - return -2; + return BITS_BTN_ERR_INVALID_PARAM; } if (config->btns_cnt > BITS_BTN_MAX_BUTTONS) { if (debug_printf) debug_printf("Error: Too many buttons (%d > max %d)\n", config->btns_cnt, (int)BITS_BTN_MAX_BUTTONS); - return -5; + return BITS_BTN_ERR_TOO_MANY_BUTTONS; } memset(button, 0, sizeof(bits_button_t)); @@ -442,7 +442,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) debug_printf("Error: Too many combo buttons (%d > max %d)\n", config->btns_combo_cnt, BITS_BTN_MAX_COMBO_BUTTONS); } - return -3; + return BITS_BTN_ERR_TOO_MANY_COMBOS; } // Check single button param pointers @@ -452,7 +452,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) { if (debug_printf) debug_printf("Error: Button[%d] param is NULL\n", i); - return -6; + return BITS_BTN_ERR_BTN_PARAM_NULL; } } @@ -463,7 +463,22 @@ int32_t bits_button_init(const bits_btn_config_t *config) { if (debug_printf) debug_printf("Error: Combo button[%d] param is NULL\n", i); - return -7; + return BITS_BTN_ERR_COMBO_PARAM_NULL; + } + } + + // Check combo button keys configuration validity + for (uint16_t i = 0; i < config->btns_combo_cnt; i++) + { + if (config->btns_combo[i].key_single_ids == NULL || + config->btns_combo[i].key_count == 0) + { + if (debug_printf) + debug_printf("Error: Combo button[%d] has invalid keys config (key_single_ids=%p, key_count=%d)\n", + i, + (void*)config->btns_combo[i].key_single_ids, + config->btns_combo[i].key_count); + return BITS_BTN_ERR_COMBO_KEYS_INVALID; } } @@ -479,7 +494,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) { if(debug_printf) debug_printf("Error, get_btn_index failed! \n"); - return -1; // Invalid ID + return BITS_BTN_ERR_INVALID_COMBO_ID; } combo->combo_mask |= ((button_mask_type_t)1UL << idx); } @@ -492,7 +507,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) if (bits_btn_buffer_ops == NULL) { if (debug_printf) debug_printf("Error: External buffer mode requires setting buffer ops!\n"); - return -4; + return BITS_BTN_ERR_BUFFER_OPS_NULL; } #endif @@ -501,7 +516,7 @@ int32_t bits_button_init(const bits_btn_config_t *config) bits_btn_buffer_ops->init(); } - return 0; + return BITS_BTN_OK; } /** diff --git a/bits_button.h b/bits_button.h index 9c01916..6d8d7bb 100644 --- a/bits_button.h +++ b/bits_button.h @@ -20,6 +20,22 @@ typedef state_bits_type_t button_mask_type_t; // Maximum number of buttons based on mask type size #define BITS_BTN_MAX_BUTTONS (sizeof(button_mask_type_t) * 8) +/** + * @brief BitsButton error codes for initialization and operation results. + * All error codes are negative values, with 0 indicating success. + */ +typedef enum { + BITS_BTN_OK = 0, // Success + BITS_BTN_ERR_INVALID_COMBO_ID = -1, // Combo button references an invalid single button ID + BITS_BTN_ERR_INVALID_PARAM = -2, // Invalid parameter (config/btns/read_func is NULL, etc.) + BITS_BTN_ERR_TOO_MANY_COMBOS = -3, // Number of combo buttons exceeds BITS_BTN_MAX_COMBO_BUTTONS + BITS_BTN_ERR_BUFFER_OPS_NULL = -4, // User buffer mode requires setting buffer ops before init + BITS_BTN_ERR_TOO_MANY_BUTTONS = -5, // Number of buttons exceeds BITS_BTN_MAX_BUTTONS + BITS_BTN_ERR_BTN_PARAM_NULL = -6, // Single button has NULL param pointer + BITS_BTN_ERR_COMBO_PARAM_NULL = -7, // Combo button has NULL param pointer + BITS_BTN_ERR_COMBO_KEYS_INVALID = -8, // Combo button keys config invalid (key_single_ids is NULL or key_count is 0) +} bits_btn_error_t; + typedef enum { BTN_STATE_IDLE , @@ -172,15 +188,16 @@ typedef struct * * @param config: Pointer to the configuration structure containing all initialization parameters. * - * @retval Status code indicating the result of the initialization: - * - 0: Success. All parameters are valid, and the button system is initialized. - * - -1: Invalid key ID in combination button configuration. - * - -2: Invalid input parameters. Returned if config is NULL or required fields are missing. - * - -3: Too many combo buttons. The number of combo buttons exceeds BITS_BTN_MAX_COMBO_BUTTONS. - * - -4: User buffer mode requires setting buffer ops before init. - * - -5: Too many buttons. The number of buttons exceeds BITS_BTN_MAX_BUTTONS. - * - -6: Button param is NULL. A single button has NULL param pointer. - * - -7: Combo button param is NULL. A combo button has NULL param pointer. + * @retval bits_btn_error_t Status code indicating the result of the initialization: + * - BITS_BTN_OK (0): Success. All parameters are valid, and the button system is initialized. + * - BITS_BTN_ERR_INVALID_COMBO_ID (-1): Invalid key ID in combination button configuration. + * - BITS_BTN_ERR_INVALID_PARAM (-2): Invalid input parameters (config/btns/read_func is NULL, etc.). + * - BITS_BTN_ERR_TOO_MANY_COMBOS (-3): Too many combo buttons (exceeds BITS_BTN_MAX_COMBO_BUTTONS). + * - BITS_BTN_ERR_BUFFER_OPS_NULL (-4): User buffer mode requires setting buffer ops before init. + * - BITS_BTN_ERR_TOO_MANY_BUTTONS (-5): Too many buttons (exceeds BITS_BTN_MAX_BUTTONS). + * - BITS_BTN_ERR_BTN_PARAM_NULL (-6): A single button has NULL param pointer. + * - BITS_BTN_ERR_COMBO_PARAM_NULL (-7): A combo button has NULL param pointer. + * - BITS_BTN_ERR_COMBO_KEYS_INVALID (-8): Combo button keys config invalid (key_single_ids is NULL or key_count is 0). */ int32_t bits_button_init(const bits_btn_config_t *config); diff --git a/docs/api.md b/docs/api.md index cbba208..4648563 100644 --- a/docs/api.md +++ b/docs/api.md @@ -14,14 +14,15 @@ int32_t bits_button_init(const bits_btn_config_t *config); - `config`: 指向配置结构体的指针，包含所有初始化参数 **返回值：** -- 0: 成功 -- -1: 组合按键配置中存在无效的按键ID -- -2: 输入参数无效 -- -3: 组合按键过多 -- -4: 需要外部缓冲区操作但未设置 -- -5: 按键数量过多 -- -6: 单按键参数无效 -- -7: 组合按键参数无效 +- `BITS_BTN_OK` (0): 成功 +- `BITS_BTN_ERR_INVALID_COMBO_ID` (-1): 组合按键配置中存在无效的按键ID +- `BITS_BTN_ERR_INVALID_PARAM` (-2): 输入参数无效（config/btns/read_func 为 NULL 等） +- `BITS_BTN_ERR_TOO_MANY_COMBOS` (-3): 组合按键数量超过 BITS_BTN_MAX_COMBO_BUTTONS +- `BITS_BTN_ERR_BUFFER_OPS_NULL` (-4): 用户缓冲区模式需要先设置 buffer ops +- `BITS_BTN_ERR_TOO_MANY_BUTTONS` (-5): 按键数量超过 BITS_BTN_MAX_BUTTONS +- `BITS_BTN_ERR_BTN_PARAM_NULL` (-6): 单按键的 param 指针为 NULL +- `BITS_BTN_ERR_COMBO_PARAM_NULL` (-7): 组合按键的 param 指针为 NULL +- `BITS_BTN_ERR_COMBO_KEYS_INVALID` (-8): 组合按键 keys 配置无效（key_single_ids 为 NULL 或 key_count 为 0） --- @@ -201,6 +202,22 @@ typedef struct button_obj_combo - `BTN_STATE_RELEASE_WINDOW`: 释放窗口 - `BTN_STATE_FINISH`: 完成 +## 错误码枚举 + +```c +typedef enum { + BITS_BTN_OK = 0, // 成功 + BITS_BTN_ERR_INVALID_COMBO_ID = -1, // 组合按键中存在无效的按键ID + BITS_BTN_ERR_INVALID_PARAM = -2, // 无效参数（config/btns/read_func为NULL等） + BITS_BTN_ERR_TOO_MANY_COMBOS = -3, // 组合按键数量超限 + BITS_BTN_ERR_BUFFER_OPS_NULL = -4, // 用户缓冲区模式需要先设置buffer ops + BITS_BTN_ERR_TOO_MANY_BUTTONS = -5, // 按键数量超限 + BITS_BTN_ERR_BTN_PARAM_NULL = -6, // 单按键param为NULL + BITS_BTN_ERR_COMBO_PARAM_NULL = -7, // 组合按键param为NULL + BITS_BTN_ERR_COMBO_KEYS_INVALID = -8, // 组合按键keys配置无效 +} bits_btn_error_t; +``` + ## 使用示例 ```c diff --git a/docs/usage_guide.md b/docs/usage_guide.md index fee512c..46bdbb6 100644 --- a/docs/usage_guide.md +++ b/docs/usage_guide.md @@ -402,3 +402,30 @@ void low_power_handler(void) { 3. **激活电平**：根据硬件电路确定（上拉电阻用1，下拉电阻用0） 4. **参数调优**：根据实际用户体验调整时间参数 5. **错误处理**：在初始化函数调用后检查返回值 + +### 错误处理示例 + +初始化函数返回 `bits_btn_error_t` 枚举类型，建议使用枚举常量进行错误处理： + +```c +int32_t ret = bits_button_init(&config); +if (ret != BITS_BTN_OK) { + switch (ret) { + case BITS_BTN_ERR_INVALID_PARAM: + printf("配置参数无效\n"); + break; + case BITS_BTN_ERR_TOO_MANY_BUTTONS: + printf("按键数量超限\n"); + break; + case BITS_BTN_ERR_BTN_PARAM_NULL: + printf("按键参数为空\n"); + break; + case BITS_BTN_ERR_COMBO_KEYS_INVALID: + printf("组合按键配置无效\n"); + break; + default: + printf("初始化失败，错误码: %d\n", ret); + break; + } +} +``` diff --git a/test/cases/edge/test_error_handling.c b/test/cases/edge/test_error_handling.c index 5640db9..347b97d 100644 --- a/test/cases/edge/test_error_handling.c +++ b/test/cases/edge/test_error_handling.c @@ -192,8 +192,9 @@ void test_resource_exhaustion(void) { }; int32_t result = bits_button_init(&config); - // 根据实现，可能成功或失败 - printf("超过最大组合按键数量的初始化结果: %d\n", result); + // 应返回组合按键数量超限错误 + TEST_ASSERT_EQUAL(-3, result); + printf("超过最大组合按键数量的初始化结果: %d (正确返回错误码 -3)\n", result); // 测试缓冲区资源耗尽（在buffer_operations.c中已测试） printf("资源耗尽测试通过: 正确处理资源限制\n"); @@ -308,4 +309,67 @@ void test_combo_button_param_null(void) { TEST_ASSERT_EQUAL(-7, result); // 应返回组合按钮 param 为空错误 printf("组合按钮 param 为 NULL 测试通过: 正确返回错误码 -7\n"); +} + +void test_combo_button_keys_invalid(void) { + printf("\n=== 测试组合按钮 keys 配置无效 ===\n"); + + static const bits_btn_obj_param_t param = TEST_DEFAULT_PARAM(); + + // 创建单按钮 + button_obj_t buttons[] = { + BITS_BUTTON_INIT(1, 1, ¶m), + BITS_BUTTON_INIT(2, 1, ¶m) + }; + + // 测试1: key_single_ids 为 NULL + printf("测试1: key_single_ids 为 NULL\n"); + button_obj_combo_t combo1 = { + .suppress = 1, + .key_count = 2, + .key_single_ids = NULL, // 无效配置 + .combo_mask = 0, + .btn = BITS_BUTTON_INIT(100, 1, ¶m) + }; + + bits_btn_config_t config1 = { + .btns = buttons, + .btns_cnt = 2, + .btns_combo = &combo1, + .btns_combo_cnt = 1, + .read_button_level_func = test_framework_mock_read_button, + .bits_btn_result_cb = test_framework_event_callback, + .bits_btn_debug_printf = test_framework_log_printf + }; + + int32_t result = bits_button_init(&config1); + TEST_ASSERT_EQUAL(-8, result); // 应返回组合按钮 keys 配置无效错误 + printf("key_single_ids 为 NULL: 正确返回错误码 -8\n"); + + // 测试2: key_count 为 0 + printf("测试2: key_count 为 0\n"); + static uint16_t combo_keys[] = {1, 2}; + button_obj_combo_t combo2 = { + .suppress = 1, + .key_count = 0, // 无效配置 + .key_single_ids = combo_keys, + .combo_mask = 0, + .btn = BITS_BUTTON_INIT(100, 1, ¶m) + }; + + bits_btn_config_t config2 = { + .btns = buttons, + .btns_cnt = 2, + .btns_combo = &combo2, + .btns_combo_cnt = 1, + .read_button_level_func = test_framework_mock_read_button, + .bits_btn_result_cb = test_framework_event_callback, + .bits_btn_debug_printf = test_framework_log_printf + }; + + result = bits_button_init(&config2); + TEST_ASSERT_EQUAL(-8, result); // 应返回组合按钮 keys 配置无效错误 + printf("key_count 为 0: 正确返回错误码 -8\n"); + + printf("组合按钮 keys 配置无效测试通过: 正确返回错误码 -8\n"); } \ No newline at end of file diff --git a/test/test_main_new.c b/test/test_main_new.c index b47d820..fe49599 100644 --- a/test/test_main_new.c +++ b/test/test_main_new.c @@ -61,6 +61,7 @@ extern void test_max_buttons_boundary(void); extern void test_too_many_buttons(void); extern void test_button_param_null(void); extern void test_combo_button_param_null(void); +extern void test_combo_button_keys_invalid(void); // 初始化测试 extern void test_successful_initialization(void); @@ -188,6 +189,7 @@ int main(void) { RUN_TEST(test_too_many_buttons); RUN_TEST(test_button_param_null); RUN_TEST(test_combo_button_param_null); + RUN_TEST(test_combo_button_keys_invalid); printf("\n【初始化配置测试】\n"); RUN_TEST(test_successful_initialization);