commit 7e2932e

add supporting documentation for public functions

 1@@ -11,6 +11,18 @@ extern int server_port;
 2 extern int http_io_timeout;
 3 extern int max_clients;
 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 void config_load(void);
18 
19 #endif /* CONFIG_H */

 1@@ -33,6 +33,14 @@ 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 int http_handle(int c);
14 
15 #endif /* HTTP_H */

 1@@ -12,8 +12,38 @@ 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 void json_free(struct json* j);
13+
14+/*
15+	Encode library to JSON
16+		@param j  Output JSON buffer (initialised by in function)
17+		@param l  Input library
18+		@return   0=Success,
19+		         -1=Failure
20+
21+	On failure, j is freed/emptied
22+*/
23 int json_library(struct json* j, const struct library* l);
24+
25+/*
26+	Encode item metadata to JSON
27+		@param j      Output JSON buffer (initialised by this function)
28+		@param it     Item (id + relative path)
29+		@param size   File size in bytes
30+		@param mtime  File modification time in epoch seconds
31+		@param type   MIME type string
32+		@return       0=Success,
33+		             -1=Failure
34+
35+	On failure, j is freed/emptied
36+*/
37 int json_meta(struct json* j, const struct item* it, size_t size, long mtime, const char* type);
38 
39 #endif /* JSON_H */

 1@@ -6,8 +6,11 @@
 2 #include <stdio.h>
 3 #include <time.h>
 4 
 5-#include "config.h"
 6-
 7+/*
 8+	Format local time as "dd/mm/YYYY HH:MM:SS"
 9+		@param  out  Output buffer (must be at least 20 bytes)
10+		@return None
11+*/
12 static inline void log_datetime(char out[20])
13 {
14 	time_t t = time(NULL);
15@@ -17,6 +20,16 @@ static inline void log_datetime(char out[20])
16 	strftime(out, 20, "%d/%m/%Y %H:%M:%S", &tmv);
17 }
18 
19+/*
20+	Print log message if verbose=true
21+		@param verbose  Whether to emit the log line
22+		@param tag      Short tag (e.g. "HTTP", "CONF")
23+		@param fmt      printf-style format string
24+		@param ap       va_list
25+		@return         None
26+
27+	In DEBUG builds, also prints [file : line : func()]
28+*/
29 static inline void log_vprint(bool verbose, const char* tag,
30 #if defined(DEBUG)
31 		const char* file, int line, const char* func,
32@@ -39,6 +52,13 @@ static inline void log_vprint(bool verbose, const char* tag,
33 	fputc('\n', stderr);
34 }
35 
36+/*
37+	Print a log message if verbose=true
38+		@param verbose  Whether to emit the log line
39+		@param tag      Short tag (e.g. "HTTP", "CONF")
40+		@param fmt      printf-style format string
41+		@return         None
42+*/
43 static inline void log_print(bool verbose, const char* tag,
44 #if defined(DEBUG)
45 		const char* file, int line, const char* func,
46@@ -57,6 +77,12 @@ static inline void log_print(bool verbose, const char* tag,
47 	va_end(ap);
48 }
49 
50+/*
51+	Log macro
52+		@param verbose_log  Whether to emit the log line
53+		@param tag          Short tag string
54+		@param fmt          printf-style format string
55+*/
56 #if defined(DEBUG)
57 #define LOG(verbose_log, tag, fmt, ...) \
58 	log_print((verbose_log), (tag), __FILE__, __LINE__, __func__, (fmt), ##__VA_ARGS__)

 1@@ -15,8 +15,33 @@ 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 void scan_library_free(struct library* l);
13+
14+/*
15+	Build library by recursively scanning given directory
16+		@param l     Output library (initialised by function)
17+		@param root  Media root directory
18+		@return      0=Success,
19+		            -1=Failure
20+*/
21 int scan_library(struct library* l, const char* root);
22+
23+/*
24+	Rescan given directory and replace current library contents
25+		@param l     Library to replace
26+		@param root  Media root directory
27+		@return      0=Success,
28+		            -1=Failure
29+
30+	On success, old library contents are freed.
31+*/
32 int scan_library_rescan(struct library* l, const char* root);
33 
34 #endif /* SCAN_H */

 1@@ -21,11 +21,58 @@ 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 bool user_allows_path(const struct user* u, const char* relpath);
15+
16+/*
17+	Add an allow prefix to the most recently pushed user
18+		@param prefix Allowed prefix (e.g. "Music/", "TV/", "*")
19+		@return       0=Success,
20+		             -1=Failure
21+*/
22 int users_add_allow(const char* prefix);
23+
24+/*
25+	Authenticate request using the "Authorization" header.
26+		@param hdr  Full HTTP request header buffer.
27+		@return     User Ptr=Success,
28+		            NULL=Failure.
29+
30+	Returns NULL if authentication is disabled
31+*/
32 const struct user* users_auth_from_hdr(const char* hdr);
33+
34+/*
35+	Free all memory owned by the global user table.
36+		@param  None
37+		@return None
38+*/
39 void users_free(void);
40+
41+/*
42+	Create new user entry and append it to the global users table
43+		@param name  Username
44+		@return      0=Success,
45+		            -1=Failure
46+*/
47 int users_push(const char* name);
48+
49+/*
50+	Set the password for most recently pushed user
51+		@param pass  Password string
52+		@return      0=Success,
53+		            -1=Failure
54+
55+	Empty password creates a passwordless user
56+*/
57 int users_set_pass(const char* pass);
58 
59 #endif /* USERS_H */

 1@@ -3,10 +3,55 @@
 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 const char* cistrstr(const char* hay, const char* nee);
13+
14+/*
15+	Extract header value from raw HTTP request header block
16+		@param out  Output buffer (NULL terminated on success)
17+		@param hdr  Raw HTTP request header block
18+		@param key  Header key to search for (case-insensitive)
19+		@return     0=Success,
20+		           -1=Not found / Malformed
21+*/
22 int hdr_get_value(char out[512], const char* hdr, const char* key);
23+
24+/*
25+	Join two path fragments
26+		@param out    Output path buffer
27+		@param outsz  Output buffer size
28+		@param a      Left path
29+		@param b      Right path
30+		@return       0=Success,
31+		             -1=Overflow / Invalid input
32+*/
33 int join_path(char* out, size_t outsz, const char* a, const char* b);
34+
35+/*
36+	Securely zero memory
37+		@param p  Pointer to memory to wipe.
38+		@param n  Number of bytes to wipe.
39+
40+	Prevents compiler from optimising the wipe away
41+*/
42 void secure_bzero(void* p, size_t n);
43+
44+/*
45+	Write exactly n bytes to a file descriptor
46+		@param fd   File descriptor
47+		@param buf  Input buffer
48+		@param n    Number of bytes to write
49+		@return     0=Success,
50+		           -1=Failure
51+
52+	Retries on EINTR.
53+*/
54 int write_all(int fd, const void* buf, size_t n);
55 
56 #endif /* UTIL_H */