Seregon/zftpd

Zero-copy FTP/HTTP Daemon compatible with all POSIX systems

C/11.0 KB/No license
include/ftp_protocol.h
raw
zftpd / include / ftp_protocol.h
1/*
2MIT License
3 
4Copyright (c) 2026 Seregon
5 
6Permission is hereby granted, free of charge, to any person obtaining a copy
7of this software and associated documentation files (the "Software"), to deal
8in the Software without restriction, including without limitation the rights
9to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10copies of the Software, and to permit persons to whom the Software is
11furnished to do so, subject to the following conditions:
12 
13The above copyright notice and this permission notice shall be included in all
14copies or substantial portions of the Software.
15 
16THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22SOFTWARE.
23*/
24 
25/**
26 * @file ftp_protocol.h
27 * @brief FTP protocol parsing and command dispatch
28 *
29 * @author SeregonWar
30 * @version 1.0.0
31 * @date 2026-02-13
32 *
33 * PROTOCOL: RFC 959 (File Transfer Protocol)
34 * EXTENSIONS: RFC 3659 (MLST, MLSD, SIZE)
35 *
36 */
37 
38#ifndef FTP_PROTOCOL_H
39#define FTP_PROTOCOL_H
40 
41#include "ftp_types.h"
42 
43/*===========================================================================*
44 * COMMAND PARSING
45 *===========================================================================*/
46 
47/**
48 * @brief Parse FTP command line
49 *
50 * Splits "COMMAND arguments\r\n" into command and arguments.
51 *
52 * EXAMPLES:
53 * "USER anonymous\r\n" -> command="USER", args="anonymous"
54 * "PWD\r\n" -> command="PWD", args=NULL
55 * "CWD /home/user\r\n" -> command="CWD", args="/home/user"
56 *
57 * @param line Input command line (null-terminated)
58 * @param command Output buffer for command name
59 * @param args Output buffer for arguments (may be NULL)
60 * @param cmd_size Size of command buffer
61 * @param args_size Size of args buffer
62 *
63 * @return FTP_OK on success, negative error code on failure
64 * @retval FTP_OK Command parsed successfully
65 * @retval FTP_ERR_INVALID_PARAM Invalid parameters
66 * @retval FTP_ERR_PROTOCOL Malformed command line
67 *
68 * @pre line != NULL
69 * @pre command != NULL
70 * @pre cmd_size > 0
71 *
72 * @post command contains uppercase command name
73 * @post args is NULL or contains arguments (trimmed)
74 *
75 * @note Thread-safety: Safe (no shared state)
76 * @note WCET: O(n) where n = strlen(line)
77 */
78ftp_error_t ftp_parse_command_line(const char *line,
79 char *command,
80 char *args,
81 size_t cmd_size,
82 size_t args_size);
83 
84/**
85 * @brief Find command handler by name
86 *
87 * @param name Command name (case-insensitive)
88 *
89 * @return Pointer to command entry, or NULL if not found
90 *
91 * @pre name != NULL
92 *
93 * @note Thread-safety: Safe (command table is const)
94 * @note WCET: O(n) where n = number of commands (~30)
95 */
96const ftp_command_entry_t* ftp_find_command(const char *name);
97 
98/**
99 * @brief Validate command arguments
100 *
101 * Checks if arguments match command requirements:
102 * - ARGS_NONE: No arguments allowed
103 * - ARGS_REQUIRED: Arguments must be present
104 * - ARGS_OPTIONAL: Arguments optional
105 *
106 * @param cmd Command entry
107 * @param args Arguments string (NULL if none)
108 *
109 * @return FTP_OK if valid, negative error code otherwise
110 *
111 * @pre cmd != NULL
112 */
113ftp_error_t ftp_validate_command_args(const ftp_command_entry_t *cmd,
114 const char *args);
115 
116/**
117 * @brief Get command table
118 *
119 * @param count Output parameter for command count
120 *
121 * @return Pointer to command table
122 *
123 * @pre count != NULL
124 *
125 * @post *count contains number of commands
126 */
127const ftp_command_entry_t* ftp_get_command_table(size_t *count);
128 
129/*===========================================================================*
130 * REPLY FORMATTING
131 *===========================================================================*/
132 
133/**
134 * @brief Format FTP reply message
135 *
136 * Creates RFC 959-compliant reply: "CODE Message\r\n"
137 *
138 * @param code FTP reply code (200-599)
139 * @param message Reply message (NULL for default)
140 * @param buffer Output buffer
141 * @param size Size of output buffer
142 *
143 * @return Number of bytes written, or negative on error
144 *
145 * @pre buffer != NULL
146 * @pre size >= 64
147 *
148 * @post buffer contains formatted reply
149 */
150ssize_t ftp_format_reply(ftp_reply_code_t code,
151 const char *message,
152 char *buffer,
153 size_t size);
154 
155/**
156 * @brief Get default message for reply code
157 *
158 * @param code FTP reply code
159 *
160 * @return Default message string, or NULL if unknown
161 */
162const char* ftp_get_default_reply_message(ftp_reply_code_t code);
163 
164#endif /* FTP_PROTOCOL_H */
165