VirtualBox

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

Last change on this file since 82731 was 82731, checked in by vboxsync, 5 years ago

iprt/ftp.h: Doxygen fix. bugref:9646
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.5 KB
Line 
1/* $Id: ftp.h 82731 2020-01-13 17:56:36Z 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 64
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 RTFTPSERVER_TRANSFER_MODE_UNKNOWN = 0,
79 RTFTPSERVER_TRANSFER_MODE_STREAM,
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 RTFTPSERVER_DATA_TYPE_UNKNOWN = 0,
92 RTFTPSERVER_DATA_TYPE_ASCII,
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 FTP server reply codes.
102 *
103 ** @todo Might needs more codes, not complete yet.
104 */
105typedef enum RTFTPSERVER_REPLY
106{
107 /** Invalid reply type, do not use. */
108 RTFTPSERVER_REPLY_INVALID = 0,
109 /** Command okay. */
110 RTFTPSERVER_REPLY_OKAY = 200,
111 /** Command not implemented, superfluous at this site. */
112 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL_SUPERFLUOUS = 202,
113 /** Service ready for new user. */
114 RTFTPSERVER_REPLY_READY_FOR_NEW_USER = 220,
115 /** Service is closing control connection. */
116 RTFTPSERVER_REPLY_CLOSING_CTRL_CONN = 221,
117 /** Closing data connection. */
118 RTFTPSERVER_REPLY_CLOSING_DATA_CONN = 226,
119 /** User logged in, proceed. */
120 RTFTPSERVER_REPLY_LOGGED_IN_PROCEED = 230,
121 /** User name okay, need password. */
122 RTFTPSERVER_REPLY_USERNAME_OKAY_NEED_PASSWORD = 331,
123 /** Can't open data connection. */
124 RTFTPSERVER_REPLY_CANT_OPEN_DATA_CONN = 425,
125 /** Connection closed; transfer aborted. */
126 RTFTPSERVER_REPLY_CONN_CLOSED_TRANSFER_ABORTED = 426,
127 /** Syntax error, command unrecognized. */
128 RTFTPSERVER_REPLY_ERROR_CMD_NOT_RECOGNIZED = 500,
129 /** Syntax error in parameters or arguments. */
130 RTFTPSERVER_REPLY_ERROR_INVALID_PARAMETERS = 501,
131 /** Command not implemented. */
132 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL = 502,
133 /** Bad sequence of commands. */
134 RTFTPSERVER_REPLY_ERROR_BAD_SEQUENCE = 503,
135 /** Command not implemented for that parameter. */
136 RTFTPSERVER_REPLY_ERROR_CMD_NOT_IMPL_PARAM = 504,
137 /** Not logged in. */
138 RTFTPSERVER_REPLY_NOT_LOGGED_IN = 530,
139 /** Requested action not taken. */
140 RTFTPSERVER_REPLY_REQ_ACTION_NOT_TAKEN = 550,
141 /** The usual 32-bit hack. */
142 RTFTPSERVER_REPLY_32BIT_HACK = 0x7fffffff
143} RTFTPSERVER_REPLY;
144
145/**
146 * Structure for maintaining a FTP server client state.
147 */
148typedef struct RTFTPSERVERCLIENTSTATE
149{
150 /** User name. */
151 char *pszUser;
152 /** Number of failed login attempts. */
153 uint8_t cFailedLoginAttempts;
154 /** Timestamp (in ms) of last command issued by the client. */
155 uint64_t tsLastCmdMs;
156 /** Current set data type. */
157 RTFTPSERVER_DATA_TYPE enmDataType;
158} RTFTPSERVERCLIENTSTATE;
159/** Pointer to a FTP server client state. */
160typedef RTFTPSERVERCLIENTSTATE *PRTFTPSERVERCLIENTSTATE;
161
162/**
163 * Structure for storing FTP server callback data.
164 */
165typedef struct RTFTPCALLBACKDATA
166{
167 /** Pointer to the client state. */
168 PRTFTPSERVERCLIENTSTATE pClient;
169 /** Saved user pointer. */
170 void *pvUser;
171 /** Size (in bytes) of data at user pointer. */
172 size_t cbUser;
173} RTFTPCALLBACKDATA;
174/** Pointer to FTP server callback data. */
175typedef RTFTPCALLBACKDATA *PRTFTPCALLBACKDATA;
176
177/**
178 * Function callback table for the FTP server implementation.
179 *
180 * All callbacks are optional and therefore can be NULL.
181 */
182typedef struct RTFTPSERVERCALLBACKS
183{
184 /** User pointer to data. Optional and can be NULL. */
185 void *pvUser;
186 /** Size (in bytes) of user data pointing at. Optional and can be 0. */
187 size_t cbUser;
188 /**
189 * Callback which gets invoked when a user connected.
190 *
191 * @returns VBox status code.
192 * @param pData Pointer to generic callback data.
193 * @param pcszUser User name.
194 */
195 DECLCALLBACKMEMBER(int, pfnOnUserConnect)(PRTFTPCALLBACKDATA pData, const char *pcszUser);
196 /**
197 * Callback which gets invoked when a user tries to authenticate with a password.
198 *
199 * @returns VBox status code.
200 * @param pData Pointer to generic callback data.
201 * @param pcszUser User name to authenticate.
202 * @param pcszPassword Password to authenticate with.
203 */
204 DECLCALLBACKMEMBER(int, pfnOnUserAuthenticate)(PRTFTPCALLBACKDATA pData, const char *pcszUser, const char *pcszPassword);
205 /**
206 * Callback which gets invoked when a user disconnected.
207 *
208 * @returns VBox status code.
209 * @param pData Pointer to generic callback data.
210 */
211 DECLCALLBACKMEMBER(int, pfnOnUserDisconnect)(PRTFTPCALLBACKDATA pData);
212 DECLCALLBACKMEMBER(int, pfnOnFileOpen)(PRTFTPCALLBACKDATA pData, const char *pcszPath, uint32_t fMode, void **ppvHandle);
213 DECLCALLBACKMEMBER(int, pfnOnFileRead)(PRTFTPCALLBACKDATA pData, void *pvHandle, void *pvBuf, size_t cbToRead, size_t *pcbRead);
214 DECLCALLBACKMEMBER(int, pfnOnFileClose)(PRTFTPCALLBACKDATA pData, void *pvHandle);
215 /**
216 * Callback which gets invoked when the client wants to retrieve the size of a specific file.
217 *
218 * @returns VBox status code.
219 * @param pData Pointer to generic callback data.
220 * @param pcszPath Path of file to retrieve size for.
221 * @param puSize Where to store the file size on success.
222 */
223 DECLCALLBACKMEMBER(int, pfnOnFileGetSize)(PRTFTPCALLBACKDATA pData, const char *pcszPath, uint64_t *puSize);
224 /**
225 * Callback which gets invoked when the client wants to retrieve information about a file.
226 *
227 * @param pData Pointer to generic callback data.
228 * @param pcszPath Path of file / directory to "stat". Optional. If NULL, the current directory will be used.
229 * @param pFsObjInfo Where to return the RTFSOBJINFO data on success. Optional.
230 * @returns VBox status code.
231 */
232 DECLCALLBACKMEMBER(int, pfnOnFileStat)(PRTFTPCALLBACKDATA pData, const char *pcszPath, PRTFSOBJINFO pFsObjInfo);
233 /**
234 * Callback which gets invoked when setting the current working directory.
235 *
236 * @returns VBox status code.
237 * @param pData Pointer to generic callback data.
238 * @param pcszCWD Current working directory to set.
239 */
240 DECLCALLBACKMEMBER(int, pfnOnPathSetCurrent)(PRTFTPCALLBACKDATA pData, const char *pcszCWD);
241 /**
242 * Callback which gets invoked when a client wants to retrieve the current working directory.
243 *
244 * @returns VBox status code.
245 * @param pData Pointer to generic callback data.
246 * @param pszPWD Where to store the current working directory.
247 * @param cbPWD Size of buffer in bytes.
248 */
249 DECLCALLBACKMEMBER(int, pfnOnPathGetCurrent)(PRTFTPCALLBACKDATA pData, char *pszPWD, size_t cbPWD);
250 /**
251 * Callback which gets invoked when the client wants to move up a directory (relative to the current working directory).
252 *
253 * @returns VBox status code.
254 * @param pData Pointer to generic callback data.
255 */
256 DECLCALLBACKMEMBER(int, pfnOnPathUp)(PRTFTPCALLBACKDATA pData);
257 /**
258 * Callback which gets invoked when the client wants to list a directory or file.
259 *
260 * @param pData Pointer to generic callback data.
261 * @param pcszPath Path of file / directory to list. Optional. If NULL, the current directory will be listed.
262 * @param ppvData Where to return the listing data. Must be free'd by the caller.
263 * @param pcbvData Where to return the listing data size in bytes.
264 * @returns VBox status code.
265 */
266 DECLCALLBACKMEMBER(int, pfnOnList)(PRTFTPCALLBACKDATA pData, const char *pcszPath, void **ppvData, size_t *pcbData);
267} RTFTPSERVERCALLBACKS;
268/** Pointer to a FTP server callback data table. */
269typedef RTFTPSERVERCALLBACKS *PRTFTPSERVERCALLBACKS;
270
271/**
272 * Creates a FTP server instance.
273 *
274 * @returns IPRT status code.
275 * @param phFTPServer Where to store the FTP server handle.
276 * @param pcszAddress The address for creating a listening socket.
277 * If NULL or empty string the server is bound to all interfaces.
278 * @param uPort The port for creating a listening socket.
279 * @param pCallbacks Callback table to use.
280 */
281RTR3DECL(int) RTFtpServerCreate(PRTFTPSERVER phFTPServer, const char *pcszAddress, uint16_t uPort,
282 PRTFTPSERVERCALLBACKS pCallbacks);
283
284/**
285 * Destroys a FTP server instance.
286 *
287 * @returns IPRT status code.
288 * @param hFTPServer Handle to the FTP server handle.
289 */
290RTR3DECL(int) RTFtpServerDestroy(RTFTPSERVER hFTPServer);
291
292/** @} */
293
294/** @} */
295RT_C_DECLS_END
296
297#endif /* !IPRT_INCLUDED_ftp_h */
298
Note: See TracBrowser for help on using the repository browser.

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