VirtualBox

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

Last change on this file since 92059 was 86973, checked in by vboxsync, 4 years ago

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette