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