xref: /PHP-8.2/ext/ftp/ftp.h (revision ac8a58fa)
1 /*
2    +----------------------------------------------------------------------+
3    | Copyright (c) The PHP Group                                          |
4    +----------------------------------------------------------------------+
5    | This source file is subject to version 3.01 of the PHP license,      |
6    | that is bundled with this package in the file LICENSE, and is        |
7    | available through the world-wide-web at the following url:           |
8    | https://www.php.net/license/3_01.txt                                 |
9    | If you did not receive a copy of the PHP license and are unable to   |
10    | obtain it through the world-wide-web, please send a note to          |
11    | license@php.net so we can mail you a copy immediately.               |
12    +----------------------------------------------------------------------+
13    | Authors: Andrew Skalski <askalski@chek.com>                          |
14    |          Stefan Esser <sesser@php.net> (resume functions)            |
15    +----------------------------------------------------------------------+
16  */
17 
18 #ifndef	FTP_H
19 #define	FTP_H
20 
21 #include "php_network.h"
22 
23 #include <stdio.h>
24 #ifdef HAVE_NETINET_IN_H
25 #include <netinet/in.h>
26 #endif
27 
28 #define	FTP_DEFAULT_TIMEOUT	90
29 #define FTP_DEFAULT_AUTOSEEK 1
30 #define FTP_DEFAULT_USEPASVADDRESS	1
31 #define PHP_FTP_FAILED			0
32 #define PHP_FTP_FINISHED		1
33 #define PHP_FTP_MOREDATA		2
34 
35 /* XXX this should be configurable at runtime XXX */
36 #define	FTP_BUFSIZE	4096
37 
38 typedef enum ftptype {
39 	FTPTYPE_ASCII=1,
40 	FTPTYPE_IMAGE
41 } ftptype_t;
42 
43 typedef struct databuf
44 {
45 	int		listener;		/* listener socket */
46 	php_socket_t		fd;			/* data connection */
47 	ftptype_t	type;			/* transfer type */
48 	char		buf[FTP_BUFSIZE];	/* data buffer */
49 #ifdef HAVE_FTP_SSL
50 	SSL		*ssl_handle;	/* ssl handle */
51 	int		ssl_active;		/* flag if ssl is active or not */
52 #endif
53 } databuf_t;
54 
55 typedef struct ftpbuf
56 {
57 	php_socket_t		fd;			/* control connection */
58 	php_sockaddr_storage	localaddr;	/* local address */
59 	int		resp;			/* last response code */
60 	char		inbuf[FTP_BUFSIZE];	/* last response text */
61 	char		*extra;			/* extra characters */
62 	int		extralen;		/* number of extra chars */
63 	char		outbuf[FTP_BUFSIZE];	/* command output buffer */
64 	char		*pwd;			/* cached pwd */
65 	char		*syst;			/* cached system type */
66 	ftptype_t	type;			/* current transfer type */
67 	int		pasv;			/* 0=off; 1=pasv; 2=ready */
68 	php_sockaddr_storage	pasvaddr;	/* passive mode address */
69 	zend_long	timeout_sec;	/* User configurable timeout (seconds) */
70 	int			autoseek;	/* User configurable autoseek flag */
71 	int			usepasvaddress;	/* Use the address returned by the pasv command */
72 
73 	int				nb;		/* "nonblocking" transfer in progress */
74 	databuf_t		*data;	/* Data connection for "nonblocking" transfers */
75 	php_stream		*stream; /* output stream for "nonblocking" transfers */
76 	int				lastch;		/* last char of previous call */
77 	int				direction;	/* recv = 0 / send = 1 */
78 	int				closestream;/* close or not close stream */
79 #ifdef HAVE_FTP_SSL
80 	int				use_ssl; /* enable(1) or disable(0) ssl */
81 	int				use_ssl_for_data; /* en/disable ssl for the dataconnection */
82 	int				old_ssl;	/* old mode = forced data encryption */
83 	SSL				*ssl_handle;      /* handle for control connection */
84 	int				ssl_active;		  /* ssl active on control conn */
85 	SSL_SESSION     *last_ssl_session; /* last negotiated session */
86 #endif
87 
88 } ftpbuf_t;
89 
90 
91 
92 /* open a FTP connection, returns ftpbuf (NULL on error)
93  * port is the ftp port in network byte order, or 0 for the default
94  */
95 ftpbuf_t*	ftp_open(const char *host, short port, zend_long timeout_sec);
96 
97 /* quits from the ftp session (it still needs to be closed)
98  * return true on success, false on error
99  */
100 int		ftp_quit(ftpbuf_t *ftp);
101 
102 /* frees up any cached data held in the ftp buffer */
103 void		ftp_gc(ftpbuf_t *ftp);
104 
105 /* close the FTP connection and return NULL */
106 ftpbuf_t*	ftp_close(ftpbuf_t *ftp);
107 
108 /* logs into the FTP server, returns true on success, false on error */
109 int		ftp_login(ftpbuf_t *ftp, const char *user, const size_t user_len, const char *pass, const size_t pass_len);
110 
111 /* reinitializes the connection, returns true on success, false on error */
112 int		ftp_reinit(ftpbuf_t *ftp);
113 
114 /* returns the remote system type (NULL on error) */
115 const char*	ftp_syst(ftpbuf_t *ftp);
116 
117 /* returns the present working directory (NULL on error) */
118 const char*	ftp_pwd(ftpbuf_t *ftp);
119 
120 /* exec a command [special features], return true on success, false on error */
121 int 	ftp_exec(ftpbuf_t *ftp, const char *cmd, const size_t cmd_len);
122 
123 /* send a raw ftp command, return response as a hashtable, NULL on error */
124 void	ftp_raw(ftpbuf_t *ftp, const char *cmd, const size_t cmd_len, zval *return_value);
125 
126 /* changes directories, return true on success, false on error */
127 int		ftp_chdir(ftpbuf_t *ftp, const char *dir, const size_t dir_len);
128 
129 /* changes to parent directory, return true on success, false on error */
130 int		ftp_cdup(ftpbuf_t *ftp);
131 
132 /* creates a directory, return the directory name on success, NULL on error.
133  * the return value must be freed
134  */
135 zend_string* ftp_mkdir(ftpbuf_t *ftp, const char *dir, const size_t dir_len);
136 
137 /* removes a directory, return true on success, false on error */
138 int		ftp_rmdir(ftpbuf_t *ftp, const char *dir, const size_t dir_len);
139 
140 /* Set permissions on a file */
141 int		ftp_chmod(ftpbuf_t *ftp, const int mode, const char *filename, const int filename_len);
142 
143 /* Allocate space on remote server with ALLO command
144  * Many servers will respond with 202 Allocation not necessary,
145  * however some servers will not accept STOR or APPE until ALLO is confirmed.
146  * If response is passed, it is estrdup()ed from ftp->inbuf and must be freed
147  * or assigned to a zval returned to the user */
148 int		ftp_alloc(ftpbuf_t *ftp, const zend_long size, zend_string **response);
149 
150 /* returns a NULL-terminated array of filenames in the given path
151  * or NULL on error.  the return array must be freed (but don't
152  * free the array elements)
153  */
154 char**		ftp_nlist(ftpbuf_t *ftp, const char *path, const size_t path_len);
155 
156 /* returns a NULL-terminated array of lines returned by the ftp
157  * LIST command for the given path or NULL on error.  the return
158  * array must be freed (but don't
159  * free the array elements)
160  */
161 char**		ftp_list(ftpbuf_t *ftp, const char *path, const size_t path_len, int recursive);
162 
163 /* populates a hashtable with the facts contained in one line of
164  * an MLSD response.
165  */
166 int			ftp_mlsd_parse_line(HashTable *ht, const char *input);
167 
168 /* returns a NULL-terminated array of lines returned by the ftp
169  * MLSD command for the given path or NULL on error.  the return
170  * array must be freed (but don't
171  * free the array elements)
172  */
173 char**		ftp_mlsd(ftpbuf_t *ftp, const char *path, const size_t path_len);
174 
175 /* switches passive mode on or off
176  * returns true on success, false on error
177  */
178 int		ftp_pasv(ftpbuf_t *ftp, int pasv);
179 
180 /* retrieves a file and saves its contents to outfp
181  * returns true on success, false on error
182  */
183 int		ftp_get(ftpbuf_t *ftp, php_stream *outstream, const char *path, const size_t path_len, ftptype_t type, zend_long resumepos);
184 
185 /* stores the data from a file, socket, or process as a file on the remote server
186  * returns true on success, false on error
187  */
188 int		ftp_put(ftpbuf_t *ftp, const char *path, const size_t path_len, php_stream *instream, ftptype_t type, zend_long startpos);
189 
190 /* append the data from a file, socket, or process as a file on the remote server
191  * returns true on success, false on error
192  */
193 int		ftp_append(ftpbuf_t *ftp, const char *path, const size_t path_len, php_stream *instream, ftptype_t type);
194 
195 /* returns the size of the given file, or -1 on error */
196 zend_long		ftp_size(ftpbuf_t *ftp, const char *path, const size_t path_len);
197 
198 /* returns the last modified time of the given file, or -1 on error */
199 time_t		ftp_mdtm(ftpbuf_t *ftp, const char *path, const size_t path_len);
200 
201 /* renames a file on the server */
202 int		ftp_rename(ftpbuf_t *ftp, const char *src, const size_t src_len, const char *dest, const size_t dest_len);
203 
204 /* deletes the file from the server */
205 int		ftp_delete(ftpbuf_t *ftp, const char *path, const size_t path_len);
206 
207 /* sends a SITE command to the server */
208 int		ftp_site(ftpbuf_t *ftp, const char *cmd, const size_t cmd_len);
209 
210 /* retrieves part of a file and saves its contents to outfp
211  * returns true on success, false on error
212  */
213 int		ftp_nb_get(ftpbuf_t *ftp, php_stream *outstream, const char *path, const size_t path_len, ftptype_t type, zend_long resumepos);
214 
215 /* stores the data from a file, socket, or process as a file on the remote server
216  * returns true on success, false on error
217  */
218 int		ftp_nb_put(ftpbuf_t *ftp, const char *path, const size_t path_len, php_stream *instream, ftptype_t type, zend_long startpos);
219 
220 /* continues a previous nb_(f)get command
221  */
222 int		ftp_nb_continue_read(ftpbuf_t *ftp);
223 
224 /* continues a previous nb_(f)put command
225  */
226 int		ftp_nb_continue_write(ftpbuf_t *ftp);
227 
228 
229 #endif
230