commit 097a8d7
uint
·
2026-04-28 19:54:34 +0000 UTC
parent d49c682
use doxygen style docs in all headers
8 files changed,
+205,
-193
+10,
-12
1@@ -12,18 +12,16 @@ extern int http_io_timeout;
2 extern int max_clients;
3 extern int auth_delay;
4
5-/*
6- Load configuration and populate global settings
7- in the order:
8- 1) $PARADOS_CONFIG
9- 2) /etc/parados.conf
10- 3) ./parados.conf
11-
12- @param None
13- @return None
14-
15- If no config is available, defaults are used
16-*/
17+/**
18+ * @brief Load configuration and populate global settings
19+ *
20+ * @note If no config is available, defaults are used
21+ *
22+ * in the order:
23+ * 1) $PARADOS_CONFIG
24+ * 2) /etc/parados.conf
25+ * 3) ./parados.conf
26+ */
27 void config_load(void);
28
29 #endif /* CONFIG_H */
+9,
-8
1@@ -33,14 +33,15 @@ enum {
2 LISTEN_BACKLOG = 64,
3 };
4
5-/*
6- Handle a single HTTP request connected socket
7- @param c Connected client socket file descriptor
8- @return 0=Handled (includes sending error responses),
9- -1=Internal Server Error
10-
11- This does not close the socket
12-*/
13+/**
14+ * @brief Handle a single HTTP request connected socket
15+ *
16+ * @note This does not close the socket
17+ *
18+ * @param c Connected client socket file descriptor
19+ *
20+ * @return 0=Handled (includes sending error responses), -1=Internal Server Error
21+ */
22 int http_handle(int c);
23
24 #endif /* HTTP_H */
+30,
-28
1@@ -12,38 +12,40 @@ struct json {
2 size_t cap;
3 };
4
5-/*
6- Free memory owned by JSON buffer
7- @param j JSON object to free
8- @return None
9-
10- Safe to call on NULL or already freed buffers
11-*/
12+/**
13+ * @brief Free memory owned by JSON buffer
14+ *
15+ * @note Safe to call on NULL or already freed buffers
16+ *
17+ * @param j JSON object to free
18+ */
19 void json_free(struct json* j);
20
21-/*
22- Encode library to JSON
23- @param j Output JSON buffer (initialised by in function)
24- @param l Input library
25- @return 0=Success,
26- -1=Failure
27-
28- On failure, j is freed/emptied
29-*/
30+/**
31+ * @brief Encode library to JSON
32+ *
33+ * @note On failure, j is freed/emptied
34+ *
35+ * @param j Output JSON buffer (initialised by in function)
36+ * @param l Input library
37+ *
38+ * @return 0=Success, -1=Failure
39+ */
40 int json_library(struct json* j, const struct library* l);
41
42-/*
43- Encode item metadata to JSON
44- @param j Output JSON buffer (initialised by this function)
45- @param it Item (id + relative path)
46- @param size File size in bytes
47- @param mtime File modification time in epoch seconds
48- @param type MIME type string
49- @return 0=Success,
50- -1=Failure
51-
52- On failure, j is freed/emptied
53-*/
54+/**
55+ * @brief Encode item metadata to JSON
56+ *
57+ * @note On failure, j is freed/emptied
58+ *
59+ * @param j Output JSON buffer (initialised by this function)
60+ * @param it Item (id + relative path)
61+ * @param size File size in bytes
62+ * @param mtime File modification time in epoch seconds
63+ * @param type MIME type string
64+ *
65+ * @return 0=Success, -1=Failure
66+ */
67 int json_meta(struct json* j, const struct item* it, size_t size, long mtime, const char* type);
68
69 #endif /* JSON_H */
+29,
-28
1@@ -6,11 +6,11 @@
2 #include <stdio.h>
3 #include <time.h>
4
5-/*
6- Format local time as "dd/mm/YYYY HH:MM:SS"
7- @param out Output buffer (must be at least 20 bytes)
8- @return None
9-*/
10+/**
11+ * @brief Format local time as "dd/mm/YYYY HH:MM:SS"
12+ *
13+ * @param out Output buffer (must be at least 20 bytes)
14+ */
15 static inline void log_datetime(char out[20])
16 {
17 time_t t = time(NULL);
18@@ -20,16 +20,16 @@ static inline void log_datetime(char out[20])
19 strftime(out, 20, "%d/%m/%Y %H:%M:%S", &tmv);
20 }
21
22-/*
23- Print log message if verbose=true
24- @param verbose Whether to emit the log line
25- @param tag Short tag (e.g. "HTTP", "CONF")
26- @param fmt printf-style format string
27- @param ap va_list
28- @return None
29-
30- In DEBUG builds, also prints [file : line : func()]
31-*/
32+/**
33+ * @brief Print log message if verbose=true
34+ *
35+ * @note In DEBUG builds, also prints [file : line : func()]
36+ *
37+ * @param verbose Whether to emit the log line
38+ * @param tag Short tag (e.g. "HTTP", "CONF")
39+ * @param fmt printf-style format string
40+ * @param ap va_list
41+ */
42 static inline void log_vprint(bool verbose, const char* tag,
43 #if defined(DEBUG)
44 const char* file, int line, const char* func,
45@@ -52,13 +52,13 @@ static inline void log_vprint(bool verbose, const char* tag,
46 fputc('\n', stderr);
47 }
48
49-/*
50- Print a log message if verbose=true
51- @param verbose Whether to emit the log line
52- @param tag Short tag (e.g. "HTTP", "CONF")
53- @param fmt printf-style format string
54- @return None
55-*/
56+/**
57+ * @brief Print a log message if verbose=true
58+ *
59+ * @param verbose Whether to emit the log line
60+ * @param tag Short tag (e.g. "HTTP", "CONF")
61+ * @param fmt printf-style format string
62+ */
63 static inline void log_print(bool verbose, const char* tag,
64 #if defined(DEBUG)
65 const char* file, int line, const char* func,
66@@ -77,12 +77,13 @@ static inline void log_print(bool verbose, const char* tag,
67 va_end(ap);
68 }
69
70-/*
71- Log macro
72- @param verbose_log Whether to emit the log line
73- @param tag Short tag string
74- @param fmt printf-style format string
75-*/
76+/**
77+ * @brief Log macro
78+ *
79+ * @param verbose_log Whether to emit the log line
80+ * @param tag Short tag string
81+ * @param fmt printf-style format string
82+ */
83 #if defined(DEBUG)
84 #define LOG(verbose_log, tag, fmt, ...) \
85 log_print((verbose_log), (tag), __FILE__, __LINE__, __func__, (fmt), ##__VA_ARGS__)
+25,
-23
1@@ -15,33 +15,35 @@ struct library {
2 size_t cap;
3 };
4
5-/*
6- Free all memory owned by a library
7- @param l Library to free
8- @return None
9-
10- Safe to call multiple times
11-*/
12+/**
13+ * @brief Free all memory owned by a library
14+ *
15+ * @note Safe to call multiple times
16+ *
17+ * @param l Library to free
18+ */
19 void scan_library_free(struct library* l);
20
21-/*
22- Build library by recursively scanning given directory
23- @param l Output library (initialised by function)
24- @param root Media root directory
25- @return 0=Success,
26- -1=Failure
27-*/
28+/**
29+ * @brief Build library by recursively scanning given directory
30+ *
31+ * @param l Output library (initialised by function)
32+ * @param root Media root directory
33+ *
34+ * @return 0=Success, -1=Failure
35+ */
36 int scan_library(struct library* l, const char* root);
37
38-/*
39- Rescan given directory and replace current library contents
40- @param l Library to replace
41- @param root Media root directory
42- @return 0=Success,
43- -1=Failure
44-
45- On success, old library contents are freed.
46-*/
47+/**
48+ * @brief Rescan given directory and replace current library contents
49+ *
50+ * @note On success, old library contents are freed.
51+ *
52+ * @param l Library to replace
53+ * @param root Media root directory
54+ *
55+ * @return 0=Success, -1=Failure
56+ */
57 int scan_library_rescan(struct library* l, const char* root);
58
59 #endif /* SCAN_H */
+43,
-42
1@@ -21,58 +21,59 @@ struct users {
2
3 extern struct users users;
4
5-/*
6- Check whether relpath is permitted for a given user.
7- @param u User entry.
8- @param relpath Path relative to media_dir.
9- @return true=permitted,
10- false=not-permitted
11-
12-TODO: use int
13-*/
14+/**
15+ * @brief Check whether relpath is permitted for a given user.
16+ *
17+ * @param u User entry.
18+ * @param relpath Path relative to media_dir.
19+ *
20+ * @return true=permitted, false=not-permitted
21+ */
22 bool user_allows_path(const struct user* u, const char* relpath);
23
24-/*
25- Add an allow prefix to the most recently pushed user
26- @param prefix Allowed prefix (e.g. "Music/", "TV/", "*")
27- @return 0=Success,
28- -1=Failure
29-*/
30+/**
31+ * @brief Add an allow prefix to the most recently pushed user
32+ *
33+ * @param prefix Allowed prefix (e.g. "Music/", "TV/", "*")
34+ *
35+ * @return 0=Success, -1=Failure
36+ */
37 int users_add_allow(const char* prefix);
38
39-/*
40- Authenticate request using the "Authorization" header.
41- @param hdr Full HTTP request header buffer.
42- @return User Ptr=Success,
43- NULL=Failure.
44-
45- Returns NULL if authentication is disabled
46-*/
47+/**
48+ * @brief Authenticate request using the "Authorization" header.
49+ *
50+ * @note Returns NULL if authentication is disabled
51+ *
52+ * @param hdr Full HTTP request header buffer.
53+ *
54+ * @return User Ptr=Success, NULL=Failure.
55+ */
56 const struct user* users_auth_from_hdr(const char* hdr);
57
58-/*
59- Free all memory owned by the global user table.
60- @param None
61- @return None
62-*/
63+/**
64+ * @brief Free all memory owned by the global user table.
65+ */
66 void users_free(void);
67
68-/*
69- Create new user entry and append it to the global users table
70- @param name Username
71- @return 0=Success,
72- -1=Failure
73-*/
74+/**
75+ * @brief Create new user entry and append it to the global users table
76+ *
77+ * @param name Username
78+ *
79+ * @return 0=Success, -1=Failure
80+ */
81 int users_push(const char* name);
82
83-/*
84- Set the password for most recently pushed user
85- @param pass Password string
86- @return 0=Success,
87- -1=Failure
88-
89- Empty password creates a passwordless user
90-*/
91+/**
92+ * @brief Set the password for most recently pushed user
93+ *
94+ * @note Empty password creates a passwordless user
95+ *
96+ * @param pass Password string
97+ *
98+ * @return 0=Success, -1=Failure
99+ */
100 int users_set_pass(const char* pass);
101
102 #endif /* USERS_H */
+46,
-41
1@@ -3,55 +3,60 @@
2
3 #include <stddef.h>
4
5-/*
6- Case-insensitive substring search
7- @param hay Haystack
8- @param nee Needle
9- @return Ptr to first match in hay,
10- NULL=Not found
11-*/
12+/**
13+ * @brief Case-insensitive substring search
14+ *
15+ * @param hay Haystack
16+ * @param nee Needle
17+ *
18+ * @return Ptr to first match in hay, NULL=Not found
19+ */
20 const char* cistrstr(const char* hay, const char* nee);
21
22-/*
23- Extract header value from raw HTTP request header block
24- @param out Output buffer (NULL terminated on success)
25- @param hdr Raw HTTP request header block
26- @param key Header key to search for (case-insensitive)
27- @return 0=Success,
28- -1=Not found / Malformed
29-*/
30+/**
31+ * @brief Extract header value from raw HTTP request header block
32+ *
33+ * @param out Output buffer (NULL terminated on success)
34+ * @param hdr Raw HTTP request header block
35+ * @param key Header key to search for (case-insensitive)
36+ *
37+ * @return 0=Success, -1=Not found / Malformed
38+ */
39 int hdr_get_value(char out[512], const char* hdr, const char* key);
40
41-/*
42- Join two path fragments
43- @param out Output path buffer
44- @param outsz Output buffer size
45- @param a Left path
46- @param b Right path
47- @return 0=Success,
48- -1=Overflow / Invalid input
49-*/
50+/**
51+ * @brief Join two path fragments
52+ *
53+ * @param out Output path buffer
54+ * @param outsz Output buffer size
55+ * @param a Left path
56+ * @param b Right path
57+ *
58+ * @return 0=Success, -1=Overflow / Invalid input
59+ */
60 int join_path(char* out, size_t outsz, const char* a, const char* b);
61
62-/*
63- Securely zero memory
64- @param p Pointer to memory to wipe.
65- @param n Number of bytes to wipe.
66-
67- Prevents compiler from optimising the wipe away
68-*/
69+/**
70+ * @brief Securely zero memory
71+ *
72+ * @note Prevents compiler from optimising the wipe away
73+ *
74+ * @param p Pointer to memory to wipe.
75+ * @param n Number of bytes to wipe.
76+ */
77 void secure_bzero(void* p, size_t n);
78
79-/*
80- Write exactly n bytes to a file descriptor
81- @param fd File descriptor
82- @param buf Input buffer
83- @param n Number of bytes to write
84- @return 0=Success,
85- -1=Failure
86-
87- Retries on EINTR.
88-*/
89+/**
90+ * @brief Write exactly n bytes to a file descriptor
91+ *
92+ * @note Retries on EINTR.
93+ *
94+ * @param fd File descriptor
95+ * @param buf Input buffer
96+ * @param n Number of bytes to write
97+ *
98+ * @return 0=Success, -1=Failure
99+ */
100 int write_all(int fd, const void* buf, size_t n);
101
102 #endif /* UTIL_H */
+13,
-11
1@@ -6,6 +6,19 @@
2
3 #include "util.h"
4
5+static int ci_key_match(const char* a, const char* b, size_t n);
6+
7+static int ci_key_match(const char* a, const char* b, size_t n)
8+{
9+ for (size_t i = 0; i < n; i++) {
10+ unsigned char ca = (unsigned char)a[i];
11+ unsigned char cb = (unsigned char)b[i];
12+ if (tolower(ca) != tolower(cb))
13+ return 0;
14+ }
15+ return 1;
16+}
17+
18 const char* cistrstr(const char* hay, const char* nee)
19 {
20 size_t nl = strlen(nee);
21@@ -35,17 +48,6 @@ const char* cistrstr(const char* hay, const char* nee)
22 return NULL;
23 }
24
25-static int ci_key_match(const char* a, const char* b, size_t n)
26-{
27- for (size_t i = 0; i < n; i++) {
28- unsigned char ca = (unsigned char)a[i];
29- unsigned char cb = (unsigned char)b[i];
30- if (tolower(ca) != tolower(cb))
31- return 0;
32- }
33- return 1;
34-}
35-
36 int hdr_get_value(char out[512], const char* hdr, const char* key)
37 {
38 size_t klen = strlen(key);