NetBurner 3.1
ftpd.h
1 /*NB_REVISION*/
2 
3 /*NB_COPYRIGHT*/
4 
5 #ifndef _NB_FTPD_H
6 #define _NB_FTPD_H
7 
8 #include <nettypes.h>
9 
10 /* Jan 16, 2008. These #defines were removed and all server functions (denoted as FTPD)
11  * were modified to use FTPD_OK and FTPD_FAIL. This was necessary so that the FTP
12  * client and server header files could be used at the same time. If you have any
13  * errors in your application code, you can salefly change all server functions from
14  * FTP_OK/FAIL to FTPD_OK/FAIL.
15  */
16 //#define FTP_FAIL (0)
17 //#define FTP_OK (1)
18 
19 #define FTPD_FAIL (0)
20 #define FTPD_OK (1)
21 #define FTPD_RUNNING (2)
22 #define FTPD_NOT_RUNNING (3)
23 #define FTPD_LISTEN_ERR (4)
24 
25 /* FTP Server Code */
26 /*Module: FTP Server
27 Implementing an FTP server in an embedded system without a built-in
28 file system is not a trivial undertaking. Most embedded applications
29 do not require a file system, and a file system is not part of the
30 standard NetBurner package. If a file system is required for a specific
31 application, it is the responsibility of the programmer to implement
32 the required features. A file system could be the trivially simple
33 example of a single file, or it could be quite complex.
34 Using the FTP Server requires that you, the programmer, write the
35 functions defined in the FTP documentation. These functions are
36 "callback" functions that allow you to customize the FTP server
37 actions to suit your particular application. All callback functions
38 required for your application must be implemented by you.
39 The NetBurner examples directory has two FTP server sample applications:
40 1. examples\ftpd_trivial - A simple system that reads and writes a single file.
41 2. examples\ftpd_expose_hml - A more complex example that exposes all of the
42  HTML served files to the FTP server. This example also shows how to upgrade
43  the NetBurner firmware and reset the system using FTP.
44 */
45 /*Functions:*/
46 /*Group:FTP Server Initialization Functions */
47 /*Initialize the FTP Server */
48 /*
49 This call starts the FTP Server task, which listens for incoming connections. Only one instance of the FTPD is allowed
50 Parameters:
51  uint16_t port The TCP port to listen to for incoming FTP requests
52  uint8_t server_priority The uC/OS task priority for the FTP Server
53 Returns:
54  FTPD_RUNNING - The FTPD is already running
55  FTPD_LISTEN_ERR - The listen socket was not able to be opened
56  FTPD_OK - The FTPD was succesfully started
57  FTPD_FAIL - The FTPD task could not be created
58 See Also:
59  void FTPDStopReq();
60 */
61 int FTPDStart(uint16_t port, uint8_t server_priority);
62 
63 /*
64 Group: FTP Server stop function
65 This function sends a stop request to the currently running FTPD.
66 Parameters:
67  none
68 Returns:
69 FTPD_RUNNING - The FTPD is still running
70 FTPD_NOT_RUNNING - The FTPD is no longer running
71 See Also:
72  int FTPDStart( uint16_t port, uint8_t server_priority );
73 */
74 int FTPDStopReq();
75 
76 /*Group: FTP Session callback typedef */
77 /*typedef for all directory reporting callbacks */
78 /*
79 This callback type definition is used by the directory reporting functions.
80 Parameters:
81  int handle The handle passed into the listing function
82  const char * name_to_report The file name to report for use in a directory listing
83 Returns:
84  FTPD_RUNNING - The FTPD is already running
85  FTPD_LISTEN_ERR - The listen socket was not able to be opened
86  FTPD_OK - The FTPD was succesfully started
87  FTPD_FAIL - The FTPD task could not be created
88 
89 See Also:
90  int FTPD_ListSubDirectories(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
91  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
92  */
93 
94 typedef void(FTPDCallBackReportFunct)(int handle, const char *name_to_report);
95 
96 /*Group: FTP Session callback functions that must be implemented by the programmer */
97 /*Functions:*/
98 /* Function called to indicate the start of a User Session. */
99 /*
100 This function is called following the creation of a new FTP session. The function needs to determine
101 the validity of the user/password pair. The returned void pointer will be passed to all access functions,
102 which will be asked to determine the validity of the operation based on the permissions
103 associated with the return value.
104 Parameters:
105  const char * user The name of the user attempting to establish an FTP session
106  const char * passwd The password of the user attempting to establish an FTP session
107  const IPADDR4 hi_ip The IP address of the server trying to establish this connection
108 Returns:
109  NULL The user name/password set is invalid
110  (obj) A non-null void pointer to an object that will be associated with this login session
111 See Also:
112  void FTPDSessionEnd(void * pSession);
113 */
114 void *FTPDSessionStart(const char *user, const char *passwd, const IPADDR4 hi_ip);
115 
116 /*Called to indicate a user session will be terminated. */
117 /*
118 This callback function gives the user program the opportunity to clean up any storage
119 associated with the void pointer returned from the FTPBSessionStart( ) call.
120 Parameters:
121  void * pSession The void * object returned from the FTPBSessionStart( ) function call
122 Returns:
123  Nothing This is a void function
124 See Also:
125  void * FTPBSessionStart(const char * user, const char * passwd, const IPADDR4 hi_ip);
126 */
127 void FTPDSessionEnd(void *pSession);
128 
129 /*Group: FTP Directory callback functions that must be implemented by the programmer */
130 /*Functions:*/
131 /* Function called by the FTP Server to test for the existence of a directory. */
132 /*
133 Called by the FTP Server as the result of an attempt to change to a new directory. This function can also
134 be used to validate the permissions of the session. This function must be implemented by
135 the programmer.
136 Parameters:
137  const char * full_directory Name of the new directory to test
138  void * pSession The void * object returned from the FTPBSessionStart( ) function call
139 Returns:
140  FTPD_OK The requested directory exists
141  FTPD_FAIL The requested directory does not exist, or access is not permitted for the user
142 See Also:
143  int FTPD_CreateSubDirectory(const char * current_directory, const char * new_dir, void * pSession);
144  int FTPD_DeleteSubDirectory(const char * current_directory, const char * sub_dir, void * pSession);
145 */
146 int FTPD_DirectoryExists(const char *full_directory, void *pSession);
147 
148 /* Function called by the FTP Server to create a directory. */
149 /*
150 Called by the FTP Server as the result of an attempt to create a new directory. This function can
151 also be used to validate the permissions of the session. This function must be implemented
152 by the programmer.
153 Parameters:
154  const char * current_directory The current value of the session directory
155  const char * new_dir The directory to create under the current_directory
156  void * pSession The void * object returned from the FTPBSessionStart( ) function call
157 Returns:
158  FTPD_OK The requested directory was created
159  FTPD_FAIL The requested directory could not be created
160 See Also:
161  int FTPD_DirectoryExists(const char * full_directory, void * pSession);
162  int FTPD_DeleteSubDirectory(const char * current_directory, const char * sub_dir, void * pSession);
163 */
164 int FTPD_CreateSubDirectory(const char *current_directory, const char *new_dir, void *pSession);
165 
166 /* Function called by the FTP Server to delete a directory. */
167 /*
168  Called by the FTP Server as the result of an attempt to delete a subdirectory. This function call can be used
169  to validate the permissions of this session. This function must be implemented by the programmer.
170 Parameters:
171  const char * current_directory The current value of the session current directory
172  const char * sub_dir The directory to delete under the current_directory
173  void * pSession The void * object returned from the FTPBSessionStart( ) function call at the beginning of the session
174 Returns:
175  FTPD_OK The requested directory was deleted
176  FTPD_FAIL The requested directory could not be deleted
177 See Also:
178  int FTPD_DirectoryExists(const char * full_directory, void * pSession);
179  int FTPD_CreateSubDirectory(const char * current_directory, const char * new_dir, void * pSession);
180 */
181 int FTPD_DeleteSubDirectory(const char *current_directory, const char *sub_dir, void *pSession);
182 
183 /* Function called by the FTP Server to list all subdirectories under the current directory. */
184 /*
185  Called by the FTP Server as the result of a client's attempt to list the contents of a directory.
186  This function must be implemented by the programmer.
187 Parameters:
188  const char * current_directory The current value of the session current directory
189  void * pSession The void * object returned from the FTPBSessionStart( ) function call
190  FTPDCallBackReportFunct * pFunc The pointer to the callback function to be called for each subdirectory
191  int handle The handle value to be passed back into the pFunc
192 Returns:
193  FTPD_OK The requested listing was successfully delivered
194  FTPD_FAIL The requested directory could not be listed
195 See Also:
196  int FTPD_DirectoryExists(const char * full_directory, void * pSession);
197  int FTPD_DeleteSubDirectory(const char * current_directory, const char * sub_dir, void * pSession);
198  int FTPD_CreateSubDirectory(const char * current_directory, const char * new_dir, void * pSession);
199 Example:
200 Everything inside the callback function stub must be supplied by the programmer. The FTP server will
201 automatically call this function and provide values for the function variables. It is the programmer's
202 responsibility to to execute pFunc( ) with the provided handle and a pointer to the string representing
203 the subdirectory name. pFunc( ) must be executed once for each subdirectory name.
204 In this example, the variables number_of_directories and DirectoryName[] must be declared and
205 initialized elsewhere in the application program.
206 int FTPD_ListSubDirectories(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
207 {
208  for (int n = 0; n < number_of_dir; n++)
209  pFunc(handle, DirectoryName[n]);
210  return FTPD_OK;
211 }
212 */
213 int FTPD_ListSubDirectories(const char *current_directory, void *pSession, FTPDCallBackReportFunct *pFunc, int handle);
214 
215 /*Group: FTP file callback functions that must be implemented by the programmer */
216 /*Functions:*/
217 /*Function to report on the whether or not a file exists */
218 /*
219 Check for the existence of a file, usually just before an attempt is made to download the file.
220 This function must be implemented by the programmer.
221 Parameters:
222  const char * full_directory The current value of the session directory
223  const char * file_name The name of the file to check
224  void * pSession The void * object returned from the FTPBSessionStart( ) function call
225 
226 Returns:
227  FTPD_OK The requested file exists
228  FTPD_FAIL The requested file does not exist
229 See Also:
230  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
231  int FTPD_SendFileToClient(const char * full_directory, const char * file_name, void * pSession, int fd);
232  int FTPD_AbleToCreateFile(const char * full_directory, const char * file_name, void * pSession);
233  int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd);
234  int FTPD_DeleteFile(const char * current_directory, const char * file_name, void * pSession);
235  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
236 */
237 int FTPD_FileExists(const char *full_directory, const char *file_name, void *pSession);
238 
239 /* returns the size of a specific file.
240 return -1 no such file.
241 return 0 file size unknown
242 return file size
243 */
244 #define FTPD_FILE_SIZE_NOSUCH_FILE (-1)
245 #define FTPD_FILE_SIZE_UNKNOWN (0)
246 int FTPD_GetFileSize(const char *full_directory, const char *file_name);
247 
248 /*Function to send the contents of a file to a file descriptor */
249 /*
250 Send a file to a FTP client. This function must be implemented by the programmer.
251 Parameters:
252  const char * full_directory. The current value of the session directory
253  const char * file_name The name of the file to send
254  void * pSession The void * object returned from the FTPBSessionStart( ) function call
255  int fd The file descriptor to send to
256 Returns:
257  FTPD_OK The requested file was sent.
258  FTPD_FAIL The requested file was not sent.
259 See Also:
260  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
261  int FTPD_AbleToCreateFile(const char * full_directory, const char * file_name, void * pSession);
262  int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd);
263  int FTPD_DeleteFile(const char * current_directory, const char * file_name, void * pSession);
264  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
265 */
266 int FTPD_SendFileToClient(const char *full_directory, const char *file_name, void *pSession, int fd);
267 
268 /*Function to report on the ability to create/receive a file. */
269 /*
270 Determine if a file can be created. This function must be implemented by the programmer.
271 Parameters:
272  const char * full_directory The current value of the session directory
273  const char * file_name The name of the file to create
274  void * pSession The void * object returned from the FTPBSessionStart( ) function call
275 Returns:
276  FTPD_OK The requested file can be written/created
277  FTPD_FAIL The requested file could not be created
278 See Also:
279  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
280  int FTPD_SendFileToClient(const char * full_directory, const char * file_name, void * pSession, int fd);
281  int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd);
282  int FTPD_DeleteFile(const char * current_directory, const char * file_name, void * pSession);
283  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
284 */
285 int FTPD_AbleToCreateFile(const char *full_directory, const char *file_name, void *pSession);
286 
287 /*Function to create/get a file */
288 /*
289 Receive a file from the FTP client. This function must be implemented by the programmer.
290 Parameters:
291  const char * full_directory The current value of the session directory
292  const char * file_name The name of the file to create
293  void * pSession The void * object returned from the FTPBSessionStart( ) function call
294  int fd The file descriptor that will be used to receive the file
295 Returns:
296  FTPD_OK The requested file was written/created
297  FTPD_FAIL The requested file was not created
298 See Also:
299  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
300  int FTPD_SendFileToClient(const char * full_directory, const char * file_name, void * pSession, int fd);
301  int FTPD_AbleToCreateFile(const char * full_directory, const char * file_name, void * pSession);
302  int FTPD_DeleteFile(const char * current_directory, const char * file_name, void * pSession);
303  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
304 */
305 int FTPD_GetFileFromClient(const char *full_directory, const char *file_name, void *pSession, int fd);
306 
307 /*User written function to delete a file */
308 /*
309 Delete a file. This function must be implemented by the programmer.
310 Parameters:
311  const char * full_directory The current value of the session directory
312  const char * file_name The name of the file to delete
313  void * pSession The void * object returned from the FTPBSessionStart( ) function call
314 Returns:
315  FTPD_OK The requested file was deleted
316  FTPD_FAIL The requested file could not be deleted
317 See Also:
318  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
319  int FTPD_SendFileToClient(const char * full_directory, const char * file_name, void * pSession, int fd);
320  int FTPD_AbleToCreateFile(const char * full_directory, const char * file_name, void * pSession);
321  int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd);
322  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
323 */
324 int FTPD_DeleteFile(const char *current_directory, const char *file_name, void *pSession);
325 
326 /*User written function to rename a file */
327 /*
328 Rename a file. This function must be implemented by the programmer.
329 Parameters:
330  const char * full_directory The current value of the session directory
331  const char * cur_file_name The name of the file to rename
332  const char * new_file_name
333  void * pSession The void * object returned from the FTPBSessionStart( ) function call
334 Returns:
335  FTPD_OK The requested file was deleted
336  FTPD_FAIL The requested file could not be renamed
337 See Also:
338  int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession);
339  int FTPD_SendFileToClient(const char * full_directory, const char * file_name, void * pSession, int fd);
340  int FTPD_AbleToCreateFile(const char * full_directory, const char * file_name, void * pSession);
341  int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd);
342  int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);
343 */
344 int FTPD_Rename(const char *current_directory, const char *cur_file_name, const char *new_file_name, void *pSession);
345 
346 /*User supplied function that lists all files in the current directory */
347 /*
348 List all files in the current directory. This function must be implemented by the programmer.
349 Parameters:
350  const char * current_directory The current value of the session directory
351  void * pSession The void * object returned from the FTPBSessionStart( ) function call
352  FTPDCallBackReportFunct * pFunc The pointer to the callback function to be called for each file name. This is a callback function
353 provided and used by the NetBurner internal FTP code. int handle The handle value to be passed back into the pFunc. This is a handle
354 provided and used by the NetBurner internal FTP code. Returns: FTPD_OK The requested files were listed FTPD_FAIL The requested file was not
355 listed See Also: int FTPD_FileExists(const char * full_directory, const char * file_name, void * pSession); int FTPD_SendFileToClient(const
356 char * full_directory, const char * file_name, void * pSession, int fd); int FTPD_AbleToCreateFile(const char * full_directory, const char *
357 file_name, void * pSession); int FTPD_GetFileFromClient(const char * full_directory, const char * file_name, void * pSession, int fd); int
358 FTPD_DeleteFile(const char * current_directory, const char * file_name, void * pSession); Example: Everything inside the callback function
359 stub must be supplied by the programmer. The FTP server will automatically call this function and provide values for the function variables.
360 It is the programmer's responsibility to to execute pFunc( ) with the provided handle and a pointer to the string representing the file
361 name. pFunc( ) must be executed once for each file name. In this example, the variables number_of_directories and FileNames[] must be
362 declared and initialized elsewhere in the application program. int FTPD_ListFile(const char * current_directory, void * pSession,
363 FTPDCallBackReportFunct * pFunc, int handle);
364 {
365  for (int n = 0; n < numberof_files; n++)
366  pFunc(handle, FileNames[n]);
367  return FTPD_OK;
368 }
369 */
370 int FTPD_ListFile(const char *current_directory, void *pSession, FTPDCallBackReportFunct *pFunc, int handle);
371 
372 #endif