qemu/roms/ipxe/src/include/ipxe/efi/efi_download.h

   1 #ifndef _IPXE_DOWNLOAD_H
   2 #define _IPXE_DOWNLOAD_H
   3
   4 /*
   5  * Copyright (C) 2010 VMware, Inc.  All Rights Reserved.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 FILE_LICENCE ( GPL2_OR_LATER );
  23
  24 /** @file
  25  *
  26  * iPXE Download Protocol
  27  *
  28  * EFI applications started by iPXE may use this interface to download files.
  29  */
  30
  31 typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL;
  32
  33 /** Token to represent a currently downloading file */
  34 typedef VOID *IPXE_DOWNLOAD_FILE;
  35
  36 /**
  37  * Callback function that is invoked when data arrives for a particular file.
  38  *
  39  * Not all protocols will deliver data in order. Clients should not rely on the
  40  * order of data delivery matching the order in the file.
  41  *
  42  * Some protocols are capable of determining the file size near the beginning
  43  * of data transfer. To allow the client to allocate memory more efficiently,
  44  * iPXE may give a hint about the file size by calling the Data callback with
  45  * a zero BufferLength and the file size in FileOffset. Clients should be
  46  * prepared to deal with more or less data than the hint actually arriving.
  47  *
  48  * @v Context           Context provided to the Start function
  49  * @v Buffer            New data
  50  * @v BufferLength      Length of new data in bytes
  51  * @v FileOffset        Offset of new data in the file
  52  * @ret Status          EFI_SUCCESS to continue the download,
  53  *                      or any error code to abort.
  54  */
  55 typedef
  56 EFI_STATUS
  57 (EFIAPI *IPXE_DOWNLOAD_DATA_CALLBACK)(
  58   IN VOID *Context,
  59   IN VOID *Buffer,
  60   IN UINTN BufferLength,
  61   IN UINTN FileOffset
  62   );
  63
  64 /**
  65  * Callback function that is invoked when the file is finished downloading, or
  66  * when a connection unexpectedly closes or times out.
  67  *
  68  * The finish callback is also called when a download is aborted by the Abort
  69  * function (below).
  70  *
  71  * @v Context           Context provided to the Start function
  72  * @v Status            Reason for termination: EFI_SUCCESS when the entire
  73  *                      file was transferred successfully, or an error
  74  *                      otherwise
  75  */
  76 typedef
  77 void
  78 (EFIAPI *IPXE_DOWNLOAD_FINISH_CALLBACK)(
  79   IN VOID *Context,
  80   IN EFI_STATUS Status
  81   );
  82
  83 /**
  84  * Start downloading a file, and register callback functions to handle the
  85  * download.
  86  *
  87  * @v This              iPXE Download Protocol instance
  88  * @v Url               URL to download from
  89  * @v DataCallback      Callback that will be invoked when data arrives
  90  * @v FinishCallback    Callback that will be invoked when the download ends
  91  * @v Context           Context passed to the Data and Finish callbacks
  92  * @v File              Token that can be used to abort the download
  93  * @ret Status          EFI status code
  94  */
  95 typedef
  96 EFI_STATUS
  97 (EFIAPI *IPXE_DOWNLOAD_START)(
  98   IN IPXE_DOWNLOAD_PROTOCOL *This,
  99   IN CHAR8 *Url,
 100   IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback,
 101   IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback,
 102   IN VOID *Context,
 103   OUT IPXE_DOWNLOAD_FILE *File
 104   );
 105
 106 /**
 107  * Forcibly abort downloading a file that is currently in progress.
 108  *
 109  * It is not safe to call this function after the Finish callback has executed.
 110  *
 111  * @v This              iPXE Download Protocol instance
 112  * @v File              Token obtained from Start
 113  * @v Status            Reason for aborting the download
 114  * @ret Status          EFI status code
 115  */
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *IPXE_DOWNLOAD_ABORT)(
 119   IN IPXE_DOWNLOAD_PROTOCOL *This,
 120   IN IPXE_DOWNLOAD_FILE File,
 121   IN EFI_STATUS Status
 122   );
 123
 124 /**
 125  * Poll for more data from iPXE. This function will invoke the registered
 126  * callbacks if data is available or if downloads complete.
 127  *
 128  * @v This              iPXE Download Protocol instance
 129  * @ret Status          EFI status code
 130  */
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI *IPXE_DOWNLOAD_POLL)(
 134   IN IPXE_DOWNLOAD_PROTOCOL *This
 135   );
 136
 137 /**
 138  * The iPXE Download Protocol.
 139  *
 140  * iPXE will attach a iPXE Download Protocol to the DeviceHandle in the Loaded
 141  * Image Protocol of all child EFI applications.
 142  */
 143 struct _IPXE_DOWNLOAD_PROTOCOL {
 144    IPXE_DOWNLOAD_START Start;
 145    IPXE_DOWNLOAD_ABORT Abort;
 146    IPXE_DOWNLOAD_POLL Poll;
 147 };
 148
 149 #define IPXE_DOWNLOAD_PROTOCOL_GUID \
 150   { \
 151     0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
 152   }
 153
 154 extern int efi_download_install ( EFI_HANDLE handle );
 155 extern void efi_download_uninstall ( EFI_HANDLE handle );
 156
 157 #endif /* _IPXE_DOWNLOAD_H */