Skip to content

ENH: 使用枚举类型 bits_btn_error_t 重构错误码返回机制 #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
530china merged 1 commit into from
Feb 8, 2026
Merged

ENH: 使用枚举类型 bits_btn_error_t 重构错误码返回机制 #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions bits_button.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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));
Expand All @@ -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
Expand All @@ -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;
}
}

Expand All @@ -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;
}
}

Expand All @@ -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);
}
Expand All @@ -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

Expand All @@ -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;
}

/**
Expand Down
35 changes: 26 additions & 9 deletions bits_button.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ,
Expand Down Expand Up @@ -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);

Expand Down
33 changes: 25 additions & 8 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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）

---

Expand Down Expand Up @@ -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
Expand Down
27 changes: 27 additions & 0 deletions docs/usage_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
}
```
68 changes: 66 additions & 2 deletions test/cases/edge/test_error_handling.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down Expand Up @@ -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, &param),
BITS_BUTTON_INIT(2, 1, &param)
};

// 测试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, &param)
};

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, &param)
};

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");
}
2 changes: 2 additions & 0 deletions test/test_main_new.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down
Loading