[mirror_edk2.git] / MdeModulePkg / Universal / Network / Mtftp4Dxe / Mtftp4Support.h

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