Seregon/zftpd

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

C/11.0 KB/No license
ffi/c_core/pal_ffi.h
raw
zftpd / ffi / c_core / pal_ffi.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 pal_ffi.h
27 * @brief C-Core Foreign Function Interface (FFI) for ZFTPD
28 *
29 * This header defines a stable, C ABI intended for consumption by
30 * high-level languages (Java, Rust, Python, Go, Zig).
31 * It uses opaque contexts (`void*`) and integer error codes to remain strictly
32 * decoupled from the internal data structures of zftpd.
33 */
34 
35#ifndef PAL_FFI_H
36#define PAL_FFI_H
37 
38#include <stddef.h>
39#include <stdint.h>
40 
41#ifdef __cplusplus
42extern "C" {
43#endif
44 
45/* Visibility macros for shared library export */
46#if defined(_WIN32) || defined(__CYGWIN__)
47#define PAL_FFI_EXPORT __declspec(dllexport)
48#else
49#define PAL_FFI_EXPORT __attribute__((visibility("default")))
50#endif
51 
52/*===========================================================================*
53 * ERROR CODES
54 * Copied from ftp_types.h to keep FFI consumers independent
55 *===========================================================================*/
56#define PAL_FFI_OK 0
57#define PAL_FFI_ERR_INVALID_PARAM -1
58#define PAL_FFI_ERR_OUT_OF_MEMORY -2
59#define PAL_FFI_ERR_UNKNOWN -99
60 
61/*===========================================================================*
62 * MEMORY ALLOCATOR (pal_alloc.h)
63 *===========================================================================*/
64 
65/**
66 * @brief Initialize the global default allocator
67 * @return PAL_FFI_OK on success, negative error code on failure
68 */
69PAL_FFI_EXPORT int pal_ffi_alloc_init_default(void);
70 
71/**
72 * @brief Allocate memory using the PAL allocator
73 * @param size Number of bytes to allocate
74 * @return Pointer to allocated memory or NULL if failed
75 */
76PAL_FFI_EXPORT void *pal_ffi_malloc(size_t size);
77 
78/**
79 * @brief Free memory using the PAL allocator
80 * @param ptr Pointer to memory to free
81 */
82PAL_FFI_EXPORT void pal_ffi_free(void *ptr);
83 
84/**
85 * @brief Allocate zero-initialized memory using the PAL allocator
86 * @param nmemb Number of elements
87 * @param size Size of each element
88 * @return Pointer to allocated memory or NULL if failed
89 */
90PAL_FFI_EXPORT void *pal_ffi_calloc(size_t nmemb, size_t size);
91 
92/**
93 * @brief Reallocate memory using the PAL allocator
94 * @param ptr Pointer to existing memory
95 * @param size New size
96 * @return Pointer to new memory or NULL if failed
97 */
98PAL_FFI_EXPORT void *pal_ffi_realloc(void *ptr, size_t size);
99 
100/**
101 * @brief Allocate aligned memory using the PAL allocator
102 * @param alignment Alignment boundary
103 * @param size Size of memory to allocate
104 * @return Pointer to allocated memory or NULL if failed
105 */
106PAL_FFI_EXPORT void *pal_ffi_aligned_alloc(size_t alignment, size_t size);
107 
108/**
109 * @brief Get total free bytes in the arena (approximate)
110 * @return Free bytes
111 */
112PAL_FFI_EXPORT size_t pal_ffi_alloc_arena_free_approx(void);
113 
114/*===========================================================================*
115 * EVENT LOOP (event_loop.h)
116 *===========================================================================*/
117 
118/**
119 * @brief Create an Event Loop context
120 * @return Opaque pointer to the event loop, or NULL on failure
121 */
122PAL_FFI_EXPORT void *pal_ffi_event_loop_create(void);
123 
124/**
125 * @brief Run the Event Loop (blocking)
126 * @param loop Opaque pointer to the event loop
127 * @return 0 on clean exit, negative on error
128 */
129PAL_FFI_EXPORT int pal_ffi_event_loop_run(void *loop);
130 
131/**
132 * @brief Stop the Event Loop
133 * @param loop Opaque pointer to the event loop
134 */
135PAL_FFI_EXPORT void pal_ffi_event_loop_stop(void *loop);
136 
137/**
138 * @brief Destroy the Event Loop and free resources
139 * @param loop Opaque pointer to the event loop
140 */
141PAL_FFI_EXPORT void pal_ffi_event_loop_destroy(void *loop);
142 
143/*===========================================================================*
144 * FTP SERVER (ftp_server.h)
145 *===========================================================================*/
146 
147/**
148 * @brief Create and initialize a new FTP server context
149 * @param bind_ip IP address to bind to ("0.0.0.0" for all)
150 * @param port Port number
151 * @param root_path Server root directory path
152 * @return Opaque pointer to the FTP server context, or NULL on failure
153 */
154PAL_FFI_EXPORT void *pal_ffi_ftp_server_create(const char *bind_ip,
155 uint16_t port,
156 const char *root_path);
157 
158/**
159 * @brief Start the FTP server (begin listening)
160 * @param server Opaque pointer to the FTP server context
161 * @return PAL_FFI_OK on success, negative error code on failure
162 */
163PAL_FFI_EXPORT int pal_ffi_ftp_server_start(void *server);
164 
165/**
166 * @brief Check if the FTP server is running
167 * @param server Opaque pointer to the FTP server context
168 * @return 1 if running, 0 if not
169 */
170PAL_FFI_EXPORT int pal_ffi_ftp_server_is_running(const void *server);
171 
172/**
173 * @brief Get the number of active FTP sessions
174 * @param server Opaque pointer to the FTP server context
175 * @return Number of active sessions
176 */
177PAL_FFI_EXPORT uint32_t
178pal_ffi_ftp_server_get_active_sessions(const void *server);
179 
180/**
181 * @brief Stop the FTP server (graceful shutdown)
182 * @param server Opaque pointer to the FTP server context
183 */
184PAL_FFI_EXPORT void pal_ffi_ftp_server_stop(void *server);
185 
186/**
187 * @brief Destroy the FTP server context and clean up resources
188 * @param server Opaque pointer to the FTP server context
189 */
190PAL_FFI_EXPORT void pal_ffi_ftp_server_destroy(void *server);
191 
192/*===========================================================================*
193 * HTTP SERVER (http_server.h)
194 *===========================================================================*/
195 
196/**
197 * @brief Create and start an HTTP server on the given port
198 * @param loop Opaque pointer to the event loop
199 * @param port Port number
200 * @return Opaque pointer to the HTTP server context, or NULL on failure
201 */
202PAL_FFI_EXPORT void *pal_ffi_http_server_create(void *loop, uint16_t port);
203 
204/**
205 * @brief Stop and destroy the HTTP server
206 * @param server Opaque pointer to the HTTP server context
207 */
208PAL_FFI_EXPORT void pal_ffi_http_server_destroy(void *server);
209 
210#ifdef __cplusplus
211}
212#endif
213 
214#endif /* PAL_FFI_H */
215