v0.0.5

src/osfp.h

@@ -8,6 +8,9 @@
 #include <linux/ipv6.h>
 #include <linux/tcp.h>
 
+/**
+ * @brief 定义操作系统类别的名称常量。
+ */
 #define OSFP_OS_CLASS_NAME_UNKNOWN   "Unknown"
 #define OSFP_OS_CLASS_NAME_WINDOWS   "Windows"
 #define OSFP_OS_CLASS_NAME_LINUX     "Linux"
@@ -16,45 +19,112 @@
 #define OSFP_OS_CLASS_NAME_ANDROID   "Android"
 #define OSFP_OS_CLASS_NAME_OTHERS    "Others"
 
+/**
+ * @brief 枚举表示不同的操作系统类别。
+ */
 enum osfp_os_class_id {
-    OSFP_OS_CLASS_UNKNOWN,
-    OSFP_OS_CLASS_WINDOWS,
-    OSFP_OS_CLASS_LINUX,
-    OSFP_OS_CLASS_MAC_OS,
-    OSFP_OS_CLASS_IOS,
-    OSFP_OS_CLASS_ANDROID,
-    OSFP_OS_CLASS_OTHERS,
+    OSFP_OS_CLASS_UNKNOWN,      // 未知
+    OSFP_OS_CLASS_WINDOWS,      // Windows
+    OSFP_OS_CLASS_LINUX,        // Linux
+    OSFP_OS_CLASS_MAC_OS,       // Mac OS
+    OSFP_OS_CLASS_IOS,          // iOS
+    OSFP_OS_CLASS_ANDROID,      // Android
+    OSFP_OS_CLASS_OTHERS,       // 其他
     OSFP_OS_CLASS_MAX,
 };
 
-struct osfp_os_result_detail {
-    unsigned int scores[OSFP_OS_CLASS_MAX];
-    unsigned int possibility[OSFP_OS_CLASS_MAX];
+/**
+ * @brief 结构体用于 osfp_result 中的详细结果。
+ */
+struct osfp_result_detail {
+    unsigned int score;         // 得分
+    unsigned int possibility;   // 可能性
 };
 
+/**
+ * @brief 结构体用于表示操作系统识别结果。
+ */
 struct osfp_result {
-    char *json_str;
-
-    enum osfp_os_class_id   likely_os_class;
-    unsigned int            likely_score;
-    unsigned int            likely_possibility;
-
-    struct osfp_os_result_detail detail;
+    char *json_str;                              // JSON 字符串
+    enum osfp_os_class_id likely_os_class;        // 最可能的操作系统类别
+    struct osfp_result_detail details[OSFP_OS_CLASS_MAX];   // 详细结果数组
 };
 
+/**
+ * @brief 结构体用于表示操作系统指纹库。
+ */
 struct osfp_db {
-    char *db_json_path;
-    void *score_db;
+    char *db_json_path;   // 操作系统指纹库 JSON 文件路径
+    void *score_db;       // 分数数据库指针
 };
 
+/**
+ * @brief 创建一个新的操作系统指纹库。
+ * 
+ * @param db_json_path 操作系统指纹库 JSON 文件的路径。
+ * @return 指向新创建的操作系统指纹库的指针。
+ */
 struct osfp_db *osfp_db_new(const char *db_json_path);
+
+/**
+ * @brief 释放操作系统指纹库占用的内存。
+ * 
+ * @param db 指向要释放的操作系统指纹库的指针。
+ */
 void osfp_db_free(struct osfp_db *db);
 
+/**
+ * @brief 通过 IPv4 头部和 TCP 头部识别操作系统。
+ * 
+ * @param db 操作系统指纹库。
+ * @param l3_hdr 指向 IPv4 头部的指针。
+ * @param l4_hdr 指向 TCP 头部的指针。
+ * @param l4_hdr_len TCP 头部的长度（注意：包含TCP选项部分）。
+ * @return 指向操作系统识别结果的指针。
+ */
 struct osfp_result *osfp_ipv4_identify(struct osfp_db *db, struct iphdr* l3_hdr, struct tcphdr *l4_hdr, size_t l4_hdr_len);
+
+/**
+ * @brief 通过 IPv6 头部和 TCP 头部识别操作系统。
+ * 
+ * @param db 操作系统指纹库。
+ * @param l3_hdr 指向 IPv6 头部的指针。
+ * @param l4_hdr 指向 TCP 头部的指针。
+ * @param l4_hdr_len TCP 头部的长度（注意：包含TCP选项部分）。
+ * @return 指向操作系统识别结果的指针（注意：内存需要使用者释放）。
+ */
 struct osfp_result *osfp_ipv6_identify(struct osfp_db *db, struct ipv6hdr* l3_hdr, struct tcphdr *l4_hdr, size_t l4_hdr_len);
 
+/**
+ * @brief 通过 json 格式的指纹识别操作系统。
+ * 
+ * @param db 操作系统指纹库。
+ * @param json_str 指纹字符串。
+ * @return 指向操作系统识别结果的指针（注意：内存需要使用者释放）。
+ */
+struct osfp_result *osfp_json_identify(struct osfp_db *db, const char *json_str);
+
+/**
+ * @brief 获取操作系统识别结果的操作系统名称。
+ * 
+ * @param result 操作系统识别结果。
+ * @return 指向操作系统名称的常量字符指针（注意：这块内存将由osfp_result_free释放）。
+ */
 const char *osfp_result_os_name_get(struct osfp_result *result);
+
+/**
+ * @brief 导出操作系统识别结果的得分详情。
+ * 
+ * @param result 操作系统识别结果。
+ * @return 指向得分详情字符串的指针（注意：内存需要使用者释放）。
+ */
 char *osfp_result_score_detail_export(struct osfp_result *result);
+
+/**
+ * @brief 释放操作系统识别结果占用的内存。
+ * 
+ * @param result 操作系统识别结果。
+ */
 void osfp_result_free(struct osfp_result *result);
 
 #endif