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