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