iPXE
efi_download.h
Go to the documentation of this file.
00001 #ifndef _IPXE_DOWNLOAD_H
00002 #define _IPXE_DOWNLOAD_H
00003 
00004 /*
00005  * Copyright (C) 2010 VMware, Inc.  All Rights Reserved.
00006  *
00007  * This program is free software; you can redistribute it and/or
00008  * modify it under the terms of the GNU General Public License as
00009  * published by the Free Software Foundation; either version 2 of the
00010  * License, or any later version.
00011  *
00012  * This program is distributed in the hope that it will be useful, but
00013  * WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00015  * General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with this program; if not, write to the Free Software
00019  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
00020  */
00021 
00022 FILE_LICENCE ( GPL2_OR_LATER );
00023 
00024 /** @file
00025  *
00026  * iPXE Download Protocol
00027  *
00028  * EFI applications started by iPXE may use this interface to download files.
00029  */
00030 
00031 typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL;
00032 
00033 /** Token to represent a currently downloading file */
00034 typedef VOID *IPXE_DOWNLOAD_FILE;
00035 
00036 /**
00037  * Callback function that is invoked when data arrives for a particular file.
00038  *
00039  * Not all protocols will deliver data in order. Clients should not rely on the
00040  * order of data delivery matching the order in the file.
00041  *
00042  * Some protocols are capable of determining the file size near the beginning
00043  * of data transfer. To allow the client to allocate memory more efficiently,
00044  * iPXE may give a hint about the file size by calling the Data callback with
00045  * a zero BufferLength and the file size in FileOffset. Clients should be
00046  * prepared to deal with more or less data than the hint actually arriving.
00047  *
00048  * @v Context           Context provided to the Start function
00049  * @v Buffer            New data
00050  * @v BufferLength      Length of new data in bytes
00051  * @v FileOffset        Offset of new data in the file
00052  * @ret Status          EFI_SUCCESS to continue the download,
00053  *                      or any error code to abort.
00054  */
00055 typedef
00056 EFI_STATUS
00057 (EFIAPI *IPXE_DOWNLOAD_DATA_CALLBACK)(
00058   IN VOID *Context,
00059   IN VOID *Buffer,
00060   IN UINTN BufferLength,
00061   IN UINTN FileOffset
00062   );
00063 
00064 /**
00065  * Callback function that is invoked when the file is finished downloading, or
00066  * when a connection unexpectedly closes or times out.
00067  *
00068  * The finish callback is also called when a download is aborted by the Abort
00069  * function (below).
00070  *
00071  * @v Context           Context provided to the Start function
00072  * @v Status            Reason for termination: EFI_SUCCESS when the entire
00073  *                      file was transferred successfully, or an error
00074  *                      otherwise
00075  */
00076 typedef
00077 void
00078 (EFIAPI *IPXE_DOWNLOAD_FINISH_CALLBACK)(
00079   IN VOID *Context,
00080   IN EFI_STATUS Status
00081   );
00082 
00083 /**
00084  * Start downloading a file, and register callback functions to handle the
00085  * download.
00086  *
00087  * @v This              iPXE Download Protocol instance
00088  * @v Url               URL to download from
00089  * @v DataCallback      Callback that will be invoked when data arrives
00090  * @v FinishCallback    Callback that will be invoked when the download ends
00091  * @v Context           Context passed to the Data and Finish callbacks
00092  * @v File              Token that can be used to abort the download
00093  * @ret Status          EFI status code
00094  */
00095 typedef
00096 EFI_STATUS
00097 (EFIAPI *IPXE_DOWNLOAD_START)(
00098   IN IPXE_DOWNLOAD_PROTOCOL *This,
00099   IN CHAR8 *Url,
00100   IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback,
00101   IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback,
00102   IN VOID *Context,
00103   OUT IPXE_DOWNLOAD_FILE *File
00104   );
00105 
00106 /**
00107  * Forcibly abort downloading a file that is currently in progress.
00108  *
00109  * It is not safe to call this function after the Finish callback has executed.
00110  *
00111  * @v This              iPXE Download Protocol instance
00112  * @v File              Token obtained from Start
00113  * @v Status            Reason for aborting the download
00114  * @ret Status          EFI status code
00115  */
00116 typedef
00117 EFI_STATUS
00118 (EFIAPI *IPXE_DOWNLOAD_ABORT)(
00119   IN IPXE_DOWNLOAD_PROTOCOL *This,
00120   IN IPXE_DOWNLOAD_FILE File,
00121   IN EFI_STATUS Status
00122   );
00123 
00124 /**
00125  * Poll for more data from iPXE. This function will invoke the registered
00126  * callbacks if data is available or if downloads complete.
00127  *
00128  * @v This              iPXE Download Protocol instance
00129  * @ret Status          EFI status code
00130  */
00131 typedef
00132 EFI_STATUS
00133 (EFIAPI *IPXE_DOWNLOAD_POLL)(
00134   IN IPXE_DOWNLOAD_PROTOCOL *This
00135   );
00136 
00137 /**
00138  * The iPXE Download Protocol.
00139  *
00140  * iPXE will attach a iPXE Download Protocol to the DeviceHandle in the Loaded
00141  * Image Protocol of all child EFI applications.
00142  */
00143 struct _IPXE_DOWNLOAD_PROTOCOL {
00144    IPXE_DOWNLOAD_START Start;
00145    IPXE_DOWNLOAD_ABORT Abort;
00146    IPXE_DOWNLOAD_POLL Poll;
00147 };
00148 
00149 #define IPXE_DOWNLOAD_PROTOCOL_GUID \
00150   { \
00151     0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
00152   }
00153 
00154 extern int efi_download_install ( EFI_HANDLE handle );
00155 extern void efi_download_uninstall ( EFI_HANDLE handle );
00156 
00157 #endif /* _IPXE_DOWNLOAD_H */