]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/Ftp4.h
MdePkg: Fix OUT parameters marked as IN OUT
[mirror_edk2.git] / MdePkg / Include / Protocol / Ftp4.h
1 /** @file
2 EFI FTPv4 (File Transfer Protocol version 4) Protocol Definition
3 The EFI FTPv4 Protocol is used to locate communication devices that are
4 supported by an EFI FTPv4 Protocol driver and to create and destroy instances
5 of the EFI FTPv4 Protocol child protocol driver that can use the underlying
6 communication device.
7 The definitions in this file are defined in UEFI Specification 2.3, which have
8 not been verified by one implementation yet.
9
10 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
11 SPDX-License-Identifier: BSD-2-Clause-Patent
12
13 @par Revision Reference:
14 This Protocol is introduced in UEFI Specification 2.2
15
16 **/
17
18 #ifndef __EFI_FTP4_PROTOCOL_H__
19 #define __EFI_FTP4_PROTOCOL_H__
20
21
22 #define EFI_FTP4_SERVICE_BINDING_PROTOCOL_GUID \
23 { \
24 0xfaaecb1, 0x226e, 0x4782, {0xaa, 0xce, 0x7d, 0xb9, 0xbc, 0xbf, 0x4d, 0xaf } \
25 }
26
27 #define EFI_FTP4_PROTOCOL_GUID \
28 { \
29 0xeb338826, 0x681b, 0x4295, {0xb3, 0x56, 0x2b, 0x36, 0x4c, 0x75, 0x7b, 0x9 } \
30 }
31
32 typedef struct _EFI_FTP4_PROTOCOL EFI_FTP4_PROTOCOL;
33
34 ///
35 /// EFI_FTP4_CONNECTION_TOKEN
36 ///
37 typedef struct {
38 ///
39 /// The Event to signal after the connection is established and Status field is updated
40 /// by the EFI FTP v4 Protocol driver. The type of Event must be
41 /// EVENT_NOTIFY_SIGNAL, and its Task Priority Level (TPL) must be lower than or
42 /// equal to TPL_CALLBACK. If it is set to NULL, this function will not return until the
43 /// function completes.
44 ///
45 EFI_EVENT Event;
46 ///
47 /// The variable to receive the result of the completed operation.
48 /// EFI_SUCCESS: The FTP connection is established successfully
49 /// EFI_ACCESS_DENIED: The FTP server denied the access the user's request to access it.
50 /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either by instance
51 /// itself or communication peer.
52 /// EFI_TIMEOUT: The connection establishment timer expired and no more specific
53 /// information is available.
54 /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable error is
55 /// received.
56 /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable error is
57 /// received.
58 /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable error is
59 /// received.
60 /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port
61 /// unreachable error is received.
62 /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP
63 /// error is received.
64 /// EFI_DEVICE_ERROR: An unexpected system or network error occurred.
65 ///
66 EFI_STATUS Status;
67 } EFI_FTP4_CONNECTION_TOKEN;
68
69 ///
70 /// EFI_FTP4_CONFIG_DATA
71 ///
72 typedef struct {
73 ///
74 /// Pointer to a ASCII string that contains user name. The caller is
75 /// responsible for freeing Username after GetModeData() is called.
76 ///
77 UINT8 *Username;
78 ///
79 /// Pointer to a ASCII string that contains password. The caller is
80 /// responsible for freeing Password after GetModeData() is called.
81 ///
82 UINT8 *Password;
83 ///
84 /// Set it to TRUE to initiate an active data connection. Set it to
85 /// FALSE to initiate a passive data connection.
86 ///
87 BOOLEAN Active;
88 ///
89 /// Boolean value indicating if default network settting used.
90 ///
91 BOOLEAN UseDefaultSetting;
92 ///
93 /// IP address of station if UseDefaultSetting is FALSE.
94 ///
95 EFI_IPv4_ADDRESS StationIp;
96 ///
97 /// Subnet mask of station if UseDefaultSetting is FALSE.
98 ///
99 EFI_IPv4_ADDRESS SubnetMask;
100 ///
101 /// IP address of gateway if UseDefaultSetting is FALSE.
102 ///
103 EFI_IPv4_ADDRESS GatewayIp;
104 ///
105 /// IP address of FTPv4 server.
106 ///
107 EFI_IPv4_ADDRESS ServerIp;
108 ///
109 /// FTPv4 server port number of control connection, and the default
110 /// value is 21 as convention.
111 ///
112 UINT16 ServerPort;
113 ///
114 /// FTPv4 server port number of data connection. If it is zero, use
115 /// (ServerPort - 1) by convention.
116 ///
117 UINT16 AltDataPort;
118 ///
119 /// A byte indicate the representation type. The right 4 bit is used for
120 /// first parameter, the left 4 bit is use for second parameter
121 /// - For the first parameter, 0x0 = image, 0x1 = EBCDIC, 0x2 = ASCII, 0x3 = local
122 /// - For the second parameter, 0x0 = Non-print, 0x1 = Telnet format effectors, 0x2 =
123 /// Carriage Control.
124 /// - If it is a local type, the second parameter is the local byte byte size.
125 /// - If it is a image type, the second parameter is undefined.
126 ///
127 UINT8 RepType;
128 ///
129 /// Defines the file structure in FTP used. 0x00 = file, 0x01 = record, 0x02 = page.
130 ///
131 UINT8 FileStruct;
132 ///
133 /// Defines the transifer mode used in FTP. 0x00 = stream, 0x01 = Block, 0x02 = Compressed.
134 ///
135 UINT8 TransMode;
136 } EFI_FTP4_CONFIG_DATA;
137
138 typedef struct _EFI_FTP4_COMMAND_TOKEN EFI_FTP4_COMMAND_TOKEN;
139
140 /**
141 Callback function when process inbound or outbound data.
142
143 If it is receiving function that leads to inbound data, the callback function
144 is called when data buffer is full. Then, old data in the data buffer should be
145 flushed and new data is stored from the beginning of data buffer.
146 If it is a transmit function that lead to outbound data and the size of
147 Data in daata buffer has been transmitted, this callback function is called to
148 supply additional data to be transmitted.
149
150 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
151 @param[in] Token Pointer to the token structure to provide the parameters that
152 are used in this operation.
153 @return User defined Status.
154
155 **/
156 typedef
157 EFI_STATUS
158 (EFIAPI *EFI_FTP4_DATA_CALLBACK)(
159 IN EFI_FTP4_PROTOCOL *This,
160 IN EFI_FTP4_COMMAND_TOKEN *Token
161 );
162
163 ///
164 /// EFI_FTP4_COMMAND_TOKEN
165 ///
166 struct _EFI_FTP4_COMMAND_TOKEN {
167 ///
168 /// The Event to signal after request is finished and Status field
169 /// is updated by the EFI FTP v4 Protocol driver. The type of Event
170 /// must be EVT_NOTIFY_SIGNAL, and its Task Priority Level
171 /// (TPL) must be lower than or equal to TPL_CALLBACK. If it is
172 /// set to NULL, related function must wait until the function
173 /// completes.
174 ///
175 EFI_EVENT Event;
176 ///
177 /// Pointer to a null-terminated ASCII name string.
178 ///
179 UINT8 *Pathname;
180 ///
181 /// The size of data buffer in bytes.
182 ///
183 UINT64 DataBufferSize;
184 ///
185 /// Pointer to the data buffer. Data downloaded from FTP server
186 /// through connection is downloaded here.
187 ///
188 VOID *DataBuffer;
189 ///
190 /// Pointer to a callback function. If it is receiving function that leads
191 /// to inbound data, the callback function is called when databuffer is
192 /// full. Then, old data in the data buffer should be flushed and new
193 /// data is stored from the beginning of data buffer. If it is a transmit
194 /// function that lead to outbound data and DataBufferSize of
195 /// Data in DataBuffer has been transmitted, this callback
196 /// function is called to supply additional data to be transmitted. The
197 /// size of additional data to be transmitted is indicated in
198 /// DataBufferSize, again. If there is no data remained,
199 /// DataBufferSize should be set to 0.
200 ///
201 EFI_FTP4_DATA_CALLBACK DataCallback;
202 ///
203 /// Pointer to the parameter for DataCallback.
204 ///
205 VOID *Context;
206 ///
207 /// The variable to receive the result of the completed operation.
208 /// EFI_SUCCESS: The FTP command is completed successfully.
209 /// EFI_ACCESS_DENIED: The FTP server denied the access to the requested file.
210 /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either
211 /// by instance itself or communication peer.
212 /// EFI_TIMEOUT: The connection establishment timer expired and no more
213 /// specific information is available.
214 /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable
215 /// error is received.
216 /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable
217 /// error is received.
218 /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable
219 /// error is received.
220 /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port
221 /// unreachable error is received.
222 /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP
223 /// error is received.
224 /// EFI_DEVICE_ERROR: An unexpected system or network error occurred.
225 ///
226 EFI_STATUS Status;
227 };
228
229 /**
230 Gets the current operational settings.
231
232 The GetModeData() function reads the current operational settings of this
233 EFI FTPv4 Protocol driver instance. EFI_FTP4_CONFIG_DATA is defined in the
234 EFI_FTP4_PROTOCOL.Configure.
235
236 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
237 @param[out] ModeData Pointer to storage for the EFI FTPv4 Protocol driver
238 mode data. The string buffers for Username and Password
239 in EFI_FTP4_CONFIG_DATA are allocated by the function,
240 and the caller should take the responsibility to free the
241 buffer later.
242
243 @retval EFI_SUCCESS This function is called successfully.
244 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
245 - This is NULL.
246 - ModeData is NULL.
247 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started
248 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
249 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
250
251 **/
252 typedef
253 EFI_STATUS
254 (EFIAPI *EFI_FTP4_GET_MODE_DATA)(
255 IN EFI_FTP4_PROTOCOL *This,
256 OUT EFI_FTP4_CONFIG_DATA *ModeData
257 );
258
259 /**
260 Disconnecting a FTP connection gracefully.
261
262 The Connect() function will initiate a connection request to the remote FTP server
263 with the corresponding connection token. If this function returns EFI_SUCCESS, the
264 connection sequence is initiated successfully. If the connection succeeds or faild
265 due to any error, the Token->Event will be signaled and Token->Status will be updated
266 accordingly.
267
268 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
269 @param[in] Token Pointer to the token used to establish control connection.
270
271 @retval EFI_SUCCESS The connection sequence is successfully initiated.
272 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
273 - This is NULL.
274 - Token is NULL.
275 - Token->Event is NULL.
276 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
277 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
278 RARP, etc.) is not finished yet.
279 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
280 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
281
282 **/
283 typedef
284 EFI_STATUS
285 (EFIAPI *EFI_FTP4_CONNECT)(
286 IN EFI_FTP4_PROTOCOL *This,
287 IN EFI_FTP4_CONNECTION_TOKEN *Token
288 );
289
290 /**
291 Disconnecting a FTP connection gracefully.
292
293 The Close() function will initiate a close request to the remote FTP server with the
294 corresponding connection token. If this function returns EFI_SUCCESS, the control
295 connection with the remote FTP server is closed.
296
297 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
298 @param[in] Token Pointer to the token used to close control connection.
299
300 @retval EFI_SUCCESS The close request is successfully initiated.
301 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
302 - This is NULL.
303 - Token is NULL.
304 - Token->Event is NULL.
305 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
306 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
307 RARP, etc.) is not finished yet.
308 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
309 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
310
311 **/
312 typedef
313 EFI_STATUS
314 (EFIAPI *EFI_FTP4_CLOSE)(
315 IN EFI_FTP4_PROTOCOL *This,
316 IN EFI_FTP4_CONNECTION_TOKEN *Token
317 );
318
319 /**
320 Sets or clears the operational parameters for the FTP child driver.
321
322 The Configure() function will configure the connected FTP session with the
323 configuration setting specified in FtpConfigData. The configuration data can
324 be reset by calling Configure() with FtpConfigData set to NULL.
325
326 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
327 @param[in] FtpConfigData Pointer to configuration data that will be assigned to
328 the FTP child driver instance. If NULL, the FTP child
329 driver instance is reset to startup defaults and all
330 pending transmit and receive requests are flushed.
331
332 @retval EFI_SUCCESS The FTPv4 driver was configured successfully.
333 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
334 - This is NULL.
335 - FtpConfigData.RepType is invalid.
336 - FtpConfigData.FileStruct is invalid.
337 - FtpConfigData.TransMode is invalid.
338 - IP address in FtpConfigData is invalid.
339 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
340 RARP, etc.) is not finished yet.
341 @retval EFI_UNSUPPORTED One or more of the configuration parameters are not supported
342 by this implementation.
343 @retval EFI_OUT_OF_RESOURCES The EFI FTPv4 Protocol driver instance data could not be
344 allocated.
345 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI FTPv4
346 Protocol driver instance is not configured.
347
348 **/
349 typedef
350 EFI_STATUS
351 (EFIAPI *EFI_FTP4_CONFIGURE)(
352 IN EFI_FTP4_PROTOCOL *This,
353 IN EFI_FTP4_CONFIG_DATA *FtpConfigData OPTIONAL
354 );
355
356
357 /**
358 Downloads a file from an FTPv4 server.
359
360 The ReadFile() function is used to initialize and start an FTPv4 download process
361 and optionally wait for completion. When the download operation completes, whether
362 successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol
363 driver and then Token.Event is signaled (if it is not NULL).
364
365 Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size
366 is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for
367 processing data and then new data will be placed at the beginning of Token.DataBuffer.
368
369 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
370 @param[in] Token Pointer to the token structure to provide the parameters that
371 are used in this operation.
372
373 @retval EFI_SUCCESS The data file is being downloaded successfully.
374 @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid.
375 - This is NULL.
376 - Token is NULL.
377 - Token.Pathname is NULL.
378 - Token. DataBuffer is NULL.
379 - Token. DataBufferSize is 0.
380 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
381 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
382 RARP, etc.) is not finished yet.
383 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
384 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
385
386 **/
387 typedef
388 EFI_STATUS
389 (EFIAPI *EFI_FTP4_READ_FILE)(
390 IN EFI_FTP4_PROTOCOL *This,
391 IN EFI_FTP4_COMMAND_TOKEN *Token
392 );
393
394 /**
395 Uploads a file from an FTPv4 server.
396
397 The WriteFile() function is used to initialize and start an FTPv4 upload process and
398 optionally wait for completion. When the upload operation completes, whether successfully
399 or not, the Token.Status field is updated by the EFI FTPv4 Protocol driver and then
400 Token.Event is signaled (if it is not NULL). Data to be uploaded to server is stored
401 into Token.DataBuffer. Token.DataBufferSize is the number bytes to be transferred.
402 If the file size is larger than Token.DataBufferSize, Token.DataCallback will be called
403 to allow for processing data and then new data will be placed at the beginning of
404 Token.DataBuffer. Token.DataBufferSize is updated to reflect the actual number of bytes
405 to be transferred. Token.DataBufferSize is set to 0 by the call back to indicate the
406 completion of data transfer.
407
408 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
409 @param[in] Token Pointer to the token structure to provide the parameters that
410 are used in this operation.
411
412 @retval EFI_SUCCESS TThe data file is being uploaded successfully.
413 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
414 @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid.
415 - This is NULL.
416 - Token is NULL.
417 - Token.Pathname is NULL.
418 - Token. DataBuffer is NULL.
419 - Token. DataBufferSize is 0.
420 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
421 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
422 RARP, etc.) is not finished yet.
423 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
424 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
425
426 **/
427 typedef
428 EFI_STATUS
429 (EFIAPI *EFI_FTP4_WRITE_FILE)(
430 IN EFI_FTP4_PROTOCOL *This,
431 IN EFI_FTP4_COMMAND_TOKEN *Token
432 );
433
434 /**
435 Download a data file "directory" from a FTPv4 server. May be unsupported in some EFI
436 implementations.
437
438 The ReadDirectory() function is used to return a list of files on the FTPv4 server that
439 logically (or operationally) related to Token.Pathname, and optionally wait for completion.
440 When the download operation completes, whether successfully or not, the Token.Status field
441 is updated by the EFI FTPv4 Protocol driver and then Token.Event is signaled (if it is not
442 NULL). Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size
443 is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for processing
444 data and then new data will be placed at the beginning of Token.DataBuffer.
445
446 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
447 @param[in] Token Pointer to the token structure to provide the parameters that
448 are used in this operation.
449
450 @retval EFI_SUCCESS The file list information is being downloaded successfully.
451 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
452 @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid.
453 - This is NULL.
454 - Token is NULL.
455 - Token. DataBuffer is NULL.
456 - Token. DataBufferSize is 0.
457 @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
458 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
459 RARP, etc.) is not finished yet.
460 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
461 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
462
463 **/
464 typedef
465 EFI_STATUS
466 (EFIAPI *EFI_FTP4_READ_DIRECTORY)(
467 IN EFI_FTP4_PROTOCOL *This,
468 IN EFI_FTP4_COMMAND_TOKEN *Token
469 );
470
471 /**
472 Polls for incoming data packets and processes outgoing data packets.
473
474 The Poll() function can be used by network drivers and applications to increase the
475 rate that data packets are moved between the communications device and the transmit
476 and receive queues. In some systems, the periodic timer event in the managed network
477 driver may not poll the underlying communications device fast enough to transmit
478 and/or receive all data packets without missing incoming packets or dropping outgoing
479 packets. Drivers and applications that are experiencing packet loss should try calling
480 the Poll() function more often.
481
482 @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
483
484 @retval EFI_SUCCESS Incoming or outgoing data was processed.
485 @retval EFI_NOT_STARTED This EFI FTPv4 Protocol instance has not been started.
486 @retval EFI_INVALID_PARAMETER This is NULL.
487 @retval EFI_DEVICE_ERROR EapAuthType An unexpected system or network error occurred.
488 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
489 Consider increasing the polling rate.
490
491 **/
492 typedef
493 EFI_STATUS
494 (EFIAPI *EFI_FTP4_POLL)(
495 IN EFI_FTP4_PROTOCOL *This
496 );
497
498 ///
499 /// EFI_FTP4_PROTOCOL
500 /// provides basic services for client-side FTP (File Transfer Protocol)
501 /// operations.
502 ///
503 struct _EFI_FTP4_PROTOCOL {
504 EFI_FTP4_GET_MODE_DATA GetModeData;
505 EFI_FTP4_CONNECT Connect;
506 EFI_FTP4_CLOSE Close;
507 EFI_FTP4_CONFIGURE Configure;
508 EFI_FTP4_READ_FILE ReadFile;
509 EFI_FTP4_WRITE_FILE WriteFile;
510 EFI_FTP4_READ_DIRECTORY ReadDirectory;
511 EFI_FTP4_POLL Poll;
512 };
513
514 extern EFI_GUID gEfiFtp4ServiceBindingProtocolGuid;
515 extern EFI_GUID gEfiFtp4ProtocolGuid;
516
517 #endif
518