iPXE
Data Structures | Macros | Typedefs | Functions
efi_download.h File Reference

iPXE Download Protocol More...

Go to the source code of this file.

Data Structures

struct  _IPXE_DOWNLOAD_PROTOCOL
 The iPXE Download Protocol. More...
 

Macros

#define IPXE_DOWNLOAD_PROTOCOL_GUID
 

Typedefs

typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL
 
typedef VOIDIPXE_DOWNLOAD_FILE
 Token to represent a currently downloading file. More...
 
typedef EFI_STATUS(EFIAPIIPXE_DOWNLOAD_DATA_CALLBACK) (IN VOID *Context, IN VOID *Buffer, IN UINTN BufferLength, IN UINTN FileOffset)
 Callback function that is invoked when data arrives for a particular file. More...
 
typedef void(EFIAPIIPXE_DOWNLOAD_FINISH_CALLBACK) (IN VOID *Context, IN EFI_STATUS Status)
 Callback function that is invoked when the file is finished downloading, or when a connection unexpectedly closes or times out. More...
 
typedef EFI_STATUS(EFIAPIIPXE_DOWNLOAD_START) (IN IPXE_DOWNLOAD_PROTOCOL *This, IN CHAR8 *Url, IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback, IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback, IN VOID *Context, OUT IPXE_DOWNLOAD_FILE *File)
 Start downloading a file, and register callback functions to handle the download. More...
 
typedef EFI_STATUS(EFIAPIIPXE_DOWNLOAD_ABORT) (IN IPXE_DOWNLOAD_PROTOCOL *This, IN IPXE_DOWNLOAD_FILE File, IN EFI_STATUS Status)
 Forcibly abort downloading a file that is currently in progress. More...
 
typedef EFI_STATUS(EFIAPIIPXE_DOWNLOAD_POLL) (IN IPXE_DOWNLOAD_PROTOCOL *This)
 Poll for more data from iPXE. More...
 

Functions

 FILE_LICENCE (GPL2_OR_LATER)
 
int efi_download_install (EFI_HANDLE handle)
 Install iPXE download protocol. More...
 
void efi_download_uninstall (EFI_HANDLE handle)
 Uninstall iPXE download protocol. More...
 

Detailed Description

iPXE Download Protocol

EFI applications started by iPXE may use this interface to download files.

Definition in file efi_download.h.

Macro Definition Documentation

◆ IPXE_DOWNLOAD_PROTOCOL_GUID

#define IPXE_DOWNLOAD_PROTOCOL_GUID
Value:
{ \
0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
}

Definition at line 149 of file efi_download.h.

Typedef Documentation

◆ IPXE_DOWNLOAD_PROTOCOL

Definition at line 31 of file efi_download.h.

◆ IPXE_DOWNLOAD_FILE

Token to represent a currently downloading file.

Definition at line 34 of file efi_download.h.

◆ IPXE_DOWNLOAD_DATA_CALLBACK

typedef EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_DATA_CALLBACK) (IN VOID *Context, IN VOID *Buffer, IN UINTN BufferLength, IN UINTN FileOffset)

Callback function that is invoked when data arrives for a particular file.

Not all protocols will deliver data in order. Clients should not rely on the order of data delivery matching the order in the file.

Some protocols are capable of determining the file size near the beginning of data transfer. To allow the client to allocate memory more efficiently, iPXE may give a hint about the file size by calling the Data callback with a zero BufferLength and the file size in FileOffset. Clients should be prepared to deal with more or less data than the hint actually arriving.

Parameters
ContextContext provided to the Start function
BufferNew data
BufferLengthLength of new data in bytes
FileOffsetOffset of new data in the file
Return values
StatusEFI_SUCCESS to continue the download, or any error code to abort.

Definition at line 57 of file efi_download.h.

◆ IPXE_DOWNLOAD_FINISH_CALLBACK

typedef void(EFIAPI * IPXE_DOWNLOAD_FINISH_CALLBACK) (IN VOID *Context, IN EFI_STATUS Status)

Callback function that is invoked when the file is finished downloading, or when a connection unexpectedly closes or times out.

The finish callback is also called when a download is aborted by the Abort function (below).

Parameters
ContextContext provided to the Start function
StatusReason for termination: EFI_SUCCESS when the entire file was transferred successfully, or an error otherwise

Definition at line 78 of file efi_download.h.

◆ IPXE_DOWNLOAD_START

typedef EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_START) (IN IPXE_DOWNLOAD_PROTOCOL *This, IN CHAR8 *Url, IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback, IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback, IN VOID *Context, OUT IPXE_DOWNLOAD_FILE *File)

Start downloading a file, and register callback functions to handle the download.

Parameters
ThisiPXE Download Protocol instance
UrlURL to download from
DataCallbackCallback that will be invoked when data arrives
FinishCallbackCallback that will be invoked when the download ends
ContextContext passed to the Data and Finish callbacks
FileToken that can be used to abort the download
Return values
StatusEFI status code

Definition at line 97 of file efi_download.h.

◆ IPXE_DOWNLOAD_ABORT

typedef EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_ABORT) (IN IPXE_DOWNLOAD_PROTOCOL *This, IN IPXE_DOWNLOAD_FILE File, IN EFI_STATUS Status)

Forcibly abort downloading a file that is currently in progress.

It is not safe to call this function after the Finish callback has executed.

Parameters
ThisiPXE Download Protocol instance
FileToken obtained from Start
StatusReason for aborting the download
Return values
StatusEFI status code

Definition at line 118 of file efi_download.h.

◆ IPXE_DOWNLOAD_POLL

typedef EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_POLL) (IN IPXE_DOWNLOAD_PROTOCOL *This)

Poll for more data from iPXE.

This function will invoke the registered callbacks if data is available or if downloads complete.

Parameters
ThisiPXE Download Protocol instance
Return values
StatusEFI status code

Definition at line 133 of file efi_download.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER  )

◆ efi_download_install()

int efi_download_install ( EFI_HANDLE  handle)

Install iPXE download protocol.

Parameters
handleEFI handle
Return values
rcReturn status code

Definition at line 211 of file efi_download.c.

211  {
213  EFI_STATUS efirc;
214  int rc;
215 
217  &handle,
220  NULL );
221  if ( efirc ) {
222  rc = -EEFI ( efirc );
223  DBG ( "Could not install download protocol: %s\n",
224  strerror ( rc ) );
225  return rc;
226  }
227 
228  return 0;
229 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2081
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:171
EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES InstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1996
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
EFI Boot Services Table.
Definition: UefiSpec.h:1917
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:199
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:31
EFI_SYSTEM_TABLE * efi_systab
#define DBG(...)
Print a debugging message.
Definition: compiler.h:498
uint16_t handle
Handle.
Definition: smbios.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
static EFI_GUID ipxe_download_protocol_guid
iPXE download protocol GUID
Definition: efi_download.c:34

References EFI_SYSTEM_TABLE::BootServices, DBG, EEFI, efi_systab, handle, EFI_BOOT_SERVICES::InstallMultipleProtocolInterfaces, ipxe_download_protocol_guid, ipxe_download_protocol_interface, NULL, rc, and strerror().

Referenced by efi_image_exec().

◆ efi_download_uninstall()

void efi_download_uninstall ( EFI_HANDLE  handle)

Uninstall iPXE download protocol.

Parameters
handleEFI handle

Definition at line 236 of file efi_download.c.

236  {
238 
240  handle,
243 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2081
EFI Boot Services Table.
Definition: UefiSpec.h:1917
EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES UninstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1997
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:199
EFI_SYSTEM_TABLE * efi_systab
uint16_t handle
Handle.
Definition: smbios.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
static EFI_GUID ipxe_download_protocol_guid
iPXE download protocol GUID
Definition: efi_download.c:34

References EFI_SYSTEM_TABLE::BootServices, efi_systab, handle, ipxe_download_protocol_guid, ipxe_download_protocol_interface, NULL, and EFI_BOOT_SERVICES::UninstallMultipleProtocolInterfaces.

Referenced by efi_image_exec().