MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Support.h

   1 /** @file
   2   Support routines for MTFTP.
   3
   4 Copyright (c) 2006, Intel Corporation<BR>
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php<BR>
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __EFI_MTFTP4_SUPPORT_H__
  16 #define __EFI_MTFTP4_SUPPORT_H__
  17
  18 //
  19 // The structure representing a range of block numbers, [Start, End].
  20 // It is used to remember the holes in the MTFTP block space. If all
  21 // the holes are filled in, then the download or upload has completed.
  22 //
  23 typedef struct {
  24   LIST_ENTRY                Link;
  25   INTN                      Start;
  26   INTN                      End;
  27 } MTFTP4_BLOCK_RANGE;
  28
  29
  30 /**
  31   Initialize the block range for either RRQ or WRQ.
  32
  33   RRQ and WRQ have different requirements for Start and End.
  34   For example, during start up, WRQ initializes its whole valid block range
  35   to [0, 0xffff]. This is bacause the server will send us a ACK0 to inform us
  36   to start the upload. When the client received ACK0, it will remove 0 from the
  37   range, get the next block number, which is 1, then upload the BLOCK1. For RRQ
  38   without option negotiation, the server will directly send us the BLOCK1 in
  39   response to the client's RRQ. When received BLOCK1, the client will remove
  40   it from the block range and send an ACK. It also works if there is option
  41   negotiation.
  42
  43   @param  Head                  The block range head to initialize
  44   @param  Start                 The Start block number.
  45   @param  End                   The last block number.
  46
  47   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for initial block range
  48   @retval EFI_SUCCESS           The initial block range is created.
  49
  50 **/
  51 EFI_STATUS
  52 Mtftp4InitBlockRange (
  53   IN LIST_ENTRY             *Head,
  54   IN UINT16                 Start,
  55   IN UINT16                 End
  56   );
  57
  58 /**
  59   Get the first valid block number on the range list.
  60
  61   @param  Head                  The block range head
  62
  63   @return The first valid block number, -1 if the block range is empty.
  64
  65 **/
  66 INTN
  67 Mtftp4GetNextBlockNum (
  68   IN LIST_ENTRY             *Head
  69   );
  70
  71 /**
  72   Set the last block number of the block range list.
  73
  74   It will remove all the blocks after the Last. MTFTP initialize the block range
  75   to the maximum possible range, such as [0, 0xffff] for WRQ. When it gets the
  76   last block number, it will call this function to set the last block number.
  77
  78   @param  Head                  The block range list
  79   @param  Last                  The last block number
  80
  81 **/
  82 VOID
  83 Mtftp4SetLastBlockNum (
  84   IN LIST_ENTRY             *Head,
  85   IN UINT16                 Last
  86   );
  87
  88 /**
  89   Remove the block number from the block range list.
  90
  91   @param  Head                  The block range list to remove from
  92   @param  Num                   The block number to remove
  93
  94   @retval EFI_NOT_FOUND         The block number isn't in the block range list
  95   @retval EFI_SUCCESS           The block number has been removed from the list
  96   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource
  97
  98 **/
  99 EFI_STATUS
 100 Mtftp4RemoveBlockNum (
 101   IN LIST_ENTRY             *Head,
 102   IN UINT16                 Num
 103   );
 104
 105 /**
 106   Set the timeout for the instance. User a longer time for passive instances.
 107
 108   @param  Instance              The Mtftp session to set time out
 109
 110 **/
 111 VOID
 112 Mtftp4SetTimeout (
 113   IN OUT MTFTP4_PROTOCOL        *Instance
 114   );
 115
 116 /**
 117   Send the packet for the instance.
 118
 119   It will first save a reference to the packet for later retransmission.
 120   Then determine the destination port, listen port for requests, and connected
 121   port for others. At last, send the packet out.
 122
 123   @param  Instance              The Mtftp instance
 124   @param  Packet                The packet to send
 125
 126   @retval EFI_SUCCESS           The packet is sent out
 127   @retval Others                Failed to transmit the packet.
 128
 129 **/
 130 EFI_STATUS
 131 Mtftp4SendPacket (
 132   IN OUT MTFTP4_PROTOCOL        *Instance,
 133   IN OUT NET_BUF                *Packet
 134   );
 135
 136 /**
 137   Build then transmit the request packet for the MTFTP session.
 138
 139   @param  Instance              The Mtftp session
 140
 141   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the request
 142   @retval EFI_SUCCESS           The request is built and sent
 143   @retval Others                Failed to transmit the packet.
 144
 145 **/
 146 EFI_STATUS
 147 Mtftp4SendRequest (
 148   IN MTFTP4_PROTOCOL        *Instance
 149   );
 150
 151 /**
 152   Build then send an error message.
 153
 154   @param  Instance              The MTFTP session
 155   @param  ErrCode               The error code
 156   @param  ErrInfo               The error message
 157
 158   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the error packet
 159   @retval EFI_SUCCESS           The error packet is transmitted.
 160   @retval Others                Failed to transmit the packet.
 161
 162 **/
 163 EFI_STATUS
 164 Mtftp4SendError (
 165   IN MTFTP4_PROTOCOL        *Instance,
 166   IN UINT16                 ErrCode,
 167   IN UINT8                  *ErrInfo
 168   );
 169
 170 /**
 171   Retransmit the last packet for the instance.
 172
 173   @param  Instance              The Mtftp instance
 174
 175   @retval EFI_SUCCESS           The last packet is retransmitted.
 176   @retval Others                Failed to retransmit.
 177
 178 **/
 179 EFI_STATUS
 180 Mtftp4Retransmit (
 181   IN MTFTP4_PROTOCOL        *Instance
 182   );
 183
 184 /**
 185   The timer ticking function for the Mtftp service instance.
 186
 187   @param  Event                 The ticking event
 188   @param  Context               The Mtftp service instance
 189
 190 **/
 191 VOID
 192 EFIAPI
 193 Mtftp4OnTimerTick (
 194   IN EFI_EVENT              Event,
 195   IN VOID                   *Context
 196   );
 197 #endif