iPXE
Data Structures | Defines | 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...

Defines

#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.
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.
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.
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.
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.
typedef EFI_STATUS(EFIAPIIPXE_DOWNLOAD_POLL )(IN IPXE_DOWNLOAD_PROTOCOL *This)
 Poll for more data from iPXE.

Functions

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

Detailed Description

iPXE Download Protocol

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

Definition in file efi_download.h.


Define Documentation

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

Definition at line 149 of file efi_download.h.


Typedef Documentation

Definition at line 31 of file efi_download.h.

Token to represent a currently downloading file.

Definition at line 34 of file efi_download.h.

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.

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.

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.

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.

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 ( GPL2_OR_LATER  )

Install iPXE download protocol.

Parameters:
handleEFI handle
Return values:
rcReturn status code

Definition at line 208 of file efi_download.c.

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

Referenced by efi_image_exec().

                                               {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_STATUS efirc;
        int rc;

        efirc = bs->InstallMultipleProtocolInterfaces (
                        &handle,
                        &ipxe_download_protocol_guid,
                        &ipxe_download_protocol_interface,
                        NULL );
        if ( efirc ) {
                rc = -EEFI ( efirc );
                DBG ( "Could not install download protocol: %s\n",
                      strerror ( rc ) );
                return rc;
        }

        return 0;
}