Mtftp4Support.h revision e5eed7d3641d71d7ea539e5379ea9c6a5cd97004 
1/** @file
2  Support routines for MTFTP.
3
4Copyright (c) 2006, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials
6are licensed and made available under the terms and conditions of the BSD License
7which accompanies this distribution.  The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php<BR>
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT 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//
23typedef 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**/
51EFI_STATUS
52Mtftp4InitBlockRange (
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**/
66INTN
67Mtftp4GetNextBlockNum (
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**/
82VOID
83Mtftp4SetLastBlockNum (
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**/
99EFI_STATUS
100Mtftp4RemoveBlockNum (
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**/
111VOID
112Mtftp4SetTimeout (
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**/
130EFI_STATUS
131Mtftp4SendPacket (
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**/
146EFI_STATUS
147Mtftp4SendRequest (
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**/
163EFI_STATUS
164Mtftp4SendError (
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**/
179EFI_STATUS
180Mtftp4Retransmit (
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**/
191VOID
192EFIAPI
193Mtftp4OnTimerTick (
194  IN EFI_EVENT              Event,
195  IN VOID                   *Context
196  );
197#endif
198