VirtualBox

source: vbox/trunk/include/iprt/ftp.h

Last change on this file was 98103, checked in by vboxsync, 16 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.1 KB
Line 
1/* $Id: ftp.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * Header file for FTP client / server implementations.
4 */
5
6/*
7 * Copyright (C) 2020-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef IPRT_INCLUDED_ftp_h
38#define IPRT_INCLUDED_ftp_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/types.h>
44#include <iprt/fs.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_ftp RTFtp - FTP server and client.
49 * @ingroup grp_rt
50 * @{
51 */
52
53/** @defgroup grp_rt_ftpserver RTFtpServer - FTP server implementation.
54 * @{
55 */
56
57/** @todo the following three definitions may move the iprt/types.h later. */
58/** FTP server handle. */
59typedef R3PTRTYPE(struct RTFTPSERVERINTERNAL *) RTFTPSERVER;
60/** Pointer to a FTP server handle. */
61typedef RTFTPSERVER *PRTFTPSERVER;
62/** Nil FTP client handle. */
63#define NIL_RTFTPSERVER ((RTFTPSERVER)0)
64
65/** Maximum length (in characters) a command can have (without parameters). */
66#define RTFTPSERVER_MAX_CMD_LEN 8
67
68/**
69 * Enumeration for defining the current server connection mode.
70 */
71typedef enum RTFTPSERVER_CONNECTION_MODE
72{
73 /** Normal mode, nothing to transfer. */
74 RTFTPSERVER_CONNECTION_MODE_NORMAL = 0,
75 /** Server is in passive mode (is listening). */
76 RTFTPSERVER_CONNECTION_MODE_PASSIVE,
77 /** Server connects via port to the client. */
78 RTFTPSERVER_CONNECTION_MODE_MODE_PORT,
79 /** The usual 32-bit hack. */
80 RTFTPSERVER_CONNECTION_MODE_32BIT_HACK = 0x7fffffff
81} RTFTPSERVER_CONNECTION_MODE;
82
83/**
84 * Enumeration for defining the data transfer mode.
85 */
86typedef enum RTFTPSERVER_TRANSFER_MODE
87{
88 /** Default if nothing else is set. */
89 RTFTPSERVER_TRANSFER_MODE_STREAM = 0,
90 RTFTPSERVER_TRANSFER_MODE_BLOCK,
91 RTFTPSERVER_TRANSFER_MODE_COMPRESSED,
92 /** The usual 32-bit hack. */
93 RTFTPSERVER_DATA_MODE_32BIT_HACK = 0x7fffffff
94} RTFTPSERVER_DATA_MODE;
95
96/**
97 * Enumeration for defining the data type.
98 */
99typedef enum RTFTPSERVER_DATA_TYPE
100{
101 /** Default if nothing else is set. */
102 RTFTPSERVER_DATA_TYPE_ASCII = 0,
103 RTFTPSERVER_DATA_TYPE_EBCDIC,
104 RTFTPSERVER_DATA_TYPE_IMAGE,
105 RTFTPSERVER_DATA_TYPE_LOCAL,
106 /** The usual 32-bit hack. */
107 RTFTPSERVER_DATA_TYPE_32BIT_HACK = 0x7fffffff
108} RTFTPSERVER_DATA_TYPE;
109
110/**
111 * Enumeration for defining the struct type.
112 */
113typedef enum RTFTPSERVER_STRUCT_TYPE
114{
115 /** Default if nothing else is set. */
116 RTFTPSERVER_STRUCT_TYPE_FILE = 0,
117 RTFTPSERVER_STRUCT_TYPE_RECORD,
118 RTFTPSERVER_STRUCT_TYPE_PAGE,
119 /** The usual 32-bit hack. */
120 RTFTPSERVER_STRUCT_TYPE_32BIT_HACK = 0x7fffffff
121} RTFTPSERVER_STRUCT_TYPE;
122
123/**
124 * Enumeration for FTP server reply codes.
125 *
126 ** @todo Might needs more codes, not complete yet.
127 */
128typedef enum RTFTPSERVER_REPLY
129{
130 /** Invalid reply type, do not use. */
131 RTFTPSERVER_REPLY_INVALID = 0,
132 /** Data connection already open. */
133 RTFTPSERVER_REPLY_DATACONN_ALREADY_OPEN = 125,
134 /** Command okay. */
135 RTFTPSERVER_REPLY_FILE_STS_OK_OPENING_DATA_CONN = 150,
136 /** Command okay. */
137 RTFTPSERVER_REPLY_OKAY = 200,
138 /** Command not implemented, superfluous at this site. */
139 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL_SUPERFLUOUS = 202,
140 /** System status report. */
141 RTFTPSERVER_REPLY_SYSTEM_STATUS = 211,
142 /** Service ready for new user. */
143 RTFTPSERVER_REPLY_READY_FOR_NEW_USER = 220,
144 /** Service is closing control connection. */
145 RTFTPSERVER_REPLY_CLOSING_CTRL_CONN = 221,
146 /** Closing data connection. */
147 RTFTPSERVER_REPLY_CLOSING_DATA_CONN = 226,
148 /** Requested file action okay, completed. */
149 RTFTPSERVER_REPLY_FILE_ACTION_OKAY_COMPLETED = 250,
150 /** "PATHNAME" ok (created / exists). */
151 RTFTPSERVER_REPLY_PATHNAME_OK = 257,
152 /** User logged in, proceed. */
153 RTFTPSERVER_REPLY_LOGGED_IN_PROCEED = 230,
154 /** User name okay, need password. */
155 RTFTPSERVER_REPLY_USERNAME_OKAY_NEED_PASSWORD = 331,
156 /** Service not available, closing control connection. */
157 RTFTPSERVER_REPLY_SVC_NOT_AVAIL_CLOSING_CTRL_CONN = 421,
158 /** Can't open data connection. */
159 RTFTPSERVER_REPLY_CANT_OPEN_DATA_CONN = 425,
160 /** Connection closed; transfer aborted. */
161 RTFTPSERVER_REPLY_CONN_CLOSED_TRANSFER_ABORTED = 426,
162 /** Requested file action not taken. */
163 RTFTPSERVER_REPLY_CONN_REQ_FILE_ACTION_NOT_TAKEN = 450,
164 /** Requested action aborted; local error in processing. */
165 RTFTPSERVER_REPLY_ACTION_ABORTED_LOCAL_ERROR = 451,
166 /** Syntax error, command unrecognized. */
167 RTFTPSERVER_REPLY_ERROR_CMD_NOT_RECOGNIZED = 500,
168 /** Syntax error in parameters or arguments. */
169 RTFTPSERVER_REPLY_ERROR_INVALID_PARAMETERS = 501,
170 /** Command not implemented. */
171 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL = 502,
172 /** Bad sequence of commands. */
173 RTFTPSERVER_REPLY_ERROR_BAD_SEQUENCE = 503,
174 /** Command not implemented for that parameter. */
175 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL_PARAM = 504,
176 /** Not logged in. */
177 RTFTPSERVER_REPLY_NOT_LOGGED_IN = 530,
178 /** Requested action not taken. */
179 RTFTPSERVER_REPLY_REQ_ACTION_NOT_TAKEN = 550,
180 /** The usual 32-bit hack. */
181 RTFTPSERVER_REPLY_32BIT_HACK = 0x7fffffff
182} RTFTPSERVER_REPLY;
183
184/**
185 * Structure for maintaining a FTP server client state.
186 */
187typedef struct RTFTPSERVERCLIENTSTATE
188{
189 /** Authenticated user (name). If NULL, no user has been logged in (yet). */
190 char *pszUser;
191 /** Current working directory.
192 * *Always* relative to the server's root directory (which is only is known to the actual implemenation). */
193 char *pszCWD;
194 /** Number of failed login attempts. */
195 uint8_t cFailedLoginAttempts;
196 /** Timestamp (in ms) of last command issued by the client. */
197 uint64_t tsLastCmdMs;
198 /** Current set data type. */
199 RTFTPSERVER_DATA_TYPE enmDataType;
200 /** Current set struct type. */
201 RTFTPSERVER_STRUCT_TYPE enmStructType;
202} RTFTPSERVERCLIENTSTATE;
203/** Pointer to a FTP server client state. */
204typedef RTFTPSERVERCLIENTSTATE *PRTFTPSERVERCLIENTSTATE;
205
206/**
207 * Structure for storing FTP server callback data.
208 */
209typedef struct RTFTPCALLBACKDATA
210{
211 /** Pointer to the client state. */
212 PRTFTPSERVERCLIENTSTATE pClient;
213 /** Saved user pointer. */
214 void *pvUser;
215 /** Size (in bytes) of data at user pointer. */
216 size_t cbUser;
217} RTFTPCALLBACKDATA;
218/** Pointer to FTP server callback data. */
219typedef RTFTPCALLBACKDATA *PRTFTPCALLBACKDATA;
220
221/**
222 * Function callback table for the FTP server implementation.
223 *
224 * All callbacks are optional and therefore can be NULL.
225 */
226typedef struct RTFTPSERVERCALLBACKS
227{
228 /**
229 * Callback which gets invoked when a user connected.
230 *
231 * @returns VBox status code.
232 * @param pData Pointer to generic callback data.
233 * @param pcszUser User name.
234 */
235 DECLCALLBACKMEMBER(int, pfnOnUserConnect,(PRTFTPCALLBACKDATA pData, const char *pcszUser));
236 /**
237 * Callback which gets invoked when a user tries to authenticate with a password.
238 *
239 * @returns VBox status code.
240 * @param pData Pointer to generic callback data.
241 * @param pcszUser User name to authenticate.
242 * @param pcszPassword Password to authenticate with.
243 */
244 DECLCALLBACKMEMBER(int, pfnOnUserAuthenticate,(PRTFTPCALLBACKDATA pData, const char *pcszUser, const char *pcszPassword));
245 /**
246 * Callback which gets invoked when a user disconnected.
247 *
248 * @returns VBox status code.
249 * @param pData Pointer to generic callback data.
250 * @param pcszUser User name which disconnected.
251 */
252 DECLCALLBACKMEMBER(int, pfnOnUserDisconnect,(PRTFTPCALLBACKDATA pData, const char *pcszUser));
253 /**
254 * Callback which gets invoked when the client wants to start reading or writing a file.
255 *
256 * @returns VBox status code.
257 * @param pData Pointer to generic callback data.
258 * @param pcsszPath Relative path (to root directory) of file to open.
259 * @param fMode File mode to use (IPRT stlye).
260 * @param ppvHandle Opaque file handle only known to the callback implementation.
261 */
262 DECLCALLBACKMEMBER(int, pfnOnFileOpen,(PRTFTPCALLBACKDATA pData, const char *pcszPath, uint32_t fMode, void **ppvHandle));
263 /**
264 * Callback which gets invoked when the client wants to read from a file.
265 *
266 * @returns VBox status code.
267 * @param pData Pointer to generic callback data.
268 * @param pvHandle Opaque file handle only known to the callback implementation.
269 * @param pvBuf Where to store the read file data.
270 * @param cbToRead How much (in bytes) to read. Must at least supply the size of pvBuf.
271 * @param pcbRead How much (in bytes) was read. Optional.
272 */
273 DECLCALLBACKMEMBER(int, pfnOnFileRead,(PRTFTPCALLBACKDATA pData, void *pvHandle, void *pvBuf, size_t cbToRead, size_t *pcbRead));
274 /**
275 * Callback which gets invoked when the client is done reading from or writing to a file.
276 *
277 * @returns VBox status code.
278 * @param pData Pointer to generic callback data.
279 * @param ppvHandle Opaque file handle only known to the callback implementation.
280 */
281 DECLCALLBACKMEMBER(int, pfnOnFileClose,(PRTFTPCALLBACKDATA pData, void *pvHandle));
282 /**
283 * Callback which gets invoked when the client wants to retrieve the size of a specific file.
284 *
285 * @returns VBox status code.
286 * @param pData Pointer to generic callback data.
287 * @param pcszPath Relative path (to root directory) of file to retrieve size for.
288 * @param puSize Where to store the file size on success.
289 */
290 DECLCALLBACKMEMBER(int, pfnOnFileGetSize,(PRTFTPCALLBACKDATA pData, const char *pcszPath, uint64_t *puSize));
291 /**
292 * Callback which gets invoked when the client wants to retrieve information about a file.
293 *
294 * @param pData Pointer to generic callback data.
295 * @param pcszPath Relative path (to root directory) of file / directory to "stat". Optional.
296 * If NULL, the current directory will be used.
297 * @param pFsObjInfo Where to return the RTFSOBJINFO data on success. Optional.
298 * @returns VBox status code.
299 */
300 DECLCALLBACKMEMBER(int, pfnOnFileStat,(PRTFTPCALLBACKDATA pData, const char *pcszPath, PRTFSOBJINFO pFsObjInfo));
301 /**
302 * Callback which gets invoked when setting the current working directory.
303 *
304 * @returns VBox status code.
305 * @param pData Pointer to generic callback data.
306 * @param pcszCWD Current working directory to set.
307 */
308 DECLCALLBACKMEMBER(int, pfnOnPathSetCurrent,(PRTFTPCALLBACKDATA pData, const char *pcszCWD));
309 /**
310 * Callback which gets invoked when a client wants to retrieve the current working directory.
311 *
312 * @returns VBox status code.
313 * @param pData Pointer to generic callback data.
314 * @param pszPWD Where to store the current working directory.
315 * @param cbPWD Size of buffer in bytes.
316 */
317 DECLCALLBACKMEMBER(int, pfnOnPathGetCurrent,(PRTFTPCALLBACKDATA pData, char *pszPWD, size_t cbPWD));
318 /**
319 * Callback which gets invoked when the client wants to move up a directory (relative to the current working directory).
320 *
321 * @returns VBox status code.
322 * @param pData Pointer to generic callback data.
323 */
324 DECLCALLBACKMEMBER(int, pfnOnPathUp,(PRTFTPCALLBACKDATA pData));
325 /**
326 * Callback which gets invoked when the server wants to open a directory for reading.
327 *
328 * @returns VBox status code. VERR_NO_MORE_FILES if listing is complete.
329 * @param pData Pointer to generic callback data.
330 * @param pcszPath Relative path (to root directory) of file / directory to list. Optional.
331 * If NULL, the current directory will be listed.
332 * @param ppvHandle Where to return the opaque directory handle.
333 */
334 DECLCALLBACKMEMBER(int, pfnOnDirOpen,(PRTFTPCALLBACKDATA pData, const char *pcszPath, void **ppvHandle));
335 /**
336 * Callback which gets invoked when the server wants to close a directory handle.
337 *
338 * @returns VBox status code. VERR_NO_MORE_FILES if listing is complete.
339 * @param pData Pointer to generic callback data.
340 * @param pvHandle Directory handle to close.
341 */
342 DECLCALLBACKMEMBER(int, pfnOnDirClose,(PRTFTPCALLBACKDATA pData, void *pvHandle));
343 /**
344 * Callback which gets invoked when the server wants to read the next directory entry.
345 *
346 * @returns VBox status code. VERR_NO_MORE_FILES if listing is complete.
347 * @param pData Pointer to generic callback data.
348 * @param pvHandle Directory handle to use for reading.
349 * @param pInfo Where to store the FS object information.
350 * @param ppszEntry Where to return the allocated string of the entry name.
351 * @param ppszOwner Where to return the allocated string of the owner.
352 * @param ppszGroup Where to return the allocated string of the group.
353 * @param ppszTarget Where to return the allocated string of the target (if a link). Currently unused.
354 */
355 DECLCALLBACKMEMBER(int, pfnOnDirRead,(PRTFTPCALLBACKDATA pData, void *pvHandle, char **ppszEntry,
356 PRTFSOBJINFO pInfo, char **ppszOwner, char **ppszGroup, char **ppszTarget));
357} RTFTPSERVERCALLBACKS;
358/** Pointer to a FTP server callback data table. */
359typedef RTFTPSERVERCALLBACKS *PRTFTPSERVERCALLBACKS;
360
361/**
362 * Creates a FTP server instance.
363 *
364 * @returns IPRT status code.
365 * @param phFTPServer Where to store the FTP server handle.
366 * @param pcszAddress The address for creating a listening socket.
367 * If NULL or empty string the server is bound to all interfaces.
368 * @param uPort The port for creating a listening socket.
369 * @param pCallbacks Callback table to use.
370 * @param pvUser Pointer to user-specific data. Optional.
371 * @param cbUser Size of user-specific data. Optional.
372 */
373RTR3DECL(int) RTFtpServerCreate(PRTFTPSERVER phFTPServer, const char *pcszAddress, uint16_t uPort,
374 PRTFTPSERVERCALLBACKS pCallbacks, void *pvUser, size_t cbUser);
375
376/**
377 * Destroys a FTP server instance.
378 *
379 * @returns IPRT status code.
380 * @param hFTPServer Handle to the FTP server handle.
381 */
382RTR3DECL(int) RTFtpServerDestroy(RTFTPSERVER hFTPServer);
383
384/** @} */
385
386/** @} */
387RT_C_DECLS_END
388
389#endif /* !IPRT_INCLUDED_ftp_h */
390
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use