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 VOID *	IPXE_DOWNLOAD_FILE
	Token to represent a currently downloading file.
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.
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.
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.
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.
typedef EFI_STATUS(EFIAPI *	IPXE_DOWNLOAD_POLL) (IN IPXE_DOWNLOAD_PROTOCOL *This)
	Poll for more data from iPXE.

Functions
	FILE_LICENCE (GPL2_OR_LATER)
	FILE_SECBOOT (PERMITTED)
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.

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 150 of file efi_download.h.

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

Typedef Documentation

IPXE_DOWNLOAD_PROTOCOL

typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL

Definition at line 32 of file efi_download.h.

IPXE_DOWNLOAD_FILE

typedef VOID* IPXE_DOWNLOAD_FILE

Token to represent a currently downloading file.

Definition at line 35 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

Context	Context provided to the Start function
Buffer	New data
BufferLength	Length of new data in bytes
FileOffset	Offset of new data in the file

Return values

Status

EFI_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

Context	Context provided to the Start function
Status	Reason 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

This	iPXE Download Protocol instance
Url	URL to download from
DataCallback	Callback that will be invoked when data arrives
FinishCallback	Callback that will be invoked when the download ends
Context	Context passed to the Data and Finish callbacks
File	Token that can be used to abort the download

Return values

Status

EFI 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

This	iPXE Download Protocol instance
File	Token obtained from Start
Status	Reason for aborting the download

Return values

Status

EFI 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

This	iPXE Download Protocol instance

Return values

Status

EFI status code

Definition at line 133 of file efi_download.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

efi_download_install()

int efi_download_install ( EFI_HANDLE handle )

extern

Install iPXE download protocol.

Parameters

handle

EFI handle

Return values

rc	Return status code

Definition at line 212 of file efi_download.c.

                                               {
        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;
}

References DBG, EEFI, EFI_HANDLE, 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 )

extern

Uninstall iPXE download protocol.

Parameters

handle

EFI handle

Definition at line 237 of file efi_download.c.

                                                  {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
 
        bs->UninstallMultipleProtocolInterfaces (
                        handle,
                        &ipxe_download_protocol_guid,
                        &ipxe_download_protocol_interface, NULL );
}

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

Referenced by efi_image_exec().