1. Sync Tcp4 protocol definitions to match UEFI 2.1
[mirror_edk2.git] / MdePkg / Include / Protocol / Tcp4.h
1 /** @file
2 EFI TCPv4 Protocol Definition
3 The EFI TCPv4 Service Binding Protocol is used to locate EFI TCPv4 Protocol drivers to create
4 and destroy child of the driver to communicate with other host using TCP protocol.
5 The EFI TCPv4 Protocol provides services to send and receive data stream.
6
7 Copyright (c) 2006, Intel Corporation
8 All rights reserved. This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
12
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16 **/
17
18 #ifndef __EFI_TCP4_PROTOCOL_H__
19 #define __EFI_TCP4_PROTOCOL_H__
20
21 #include <Protocol/Ip4.h>
22
23 #define EFI_TCP4_SERVICE_BINDING_PROTOCOL_GUID \
24 { \
25 0x00720665, 0x67EB, 0x4a99, {0xBA, 0xF7, 0xD3, 0xC3, 0x3A, 0x1C, 0x7C, 0xC9 } \
26 }
27
28 #define EFI_TCP4_PROTOCOL_GUID \
29 { \
30 0x65530BC7, 0xA359, 0x410f, {0xB0, 0x10, 0x5A, 0xAD, 0xC7, 0xEC, 0x2B, 0x62 } \
31 }
32
33 typedef struct _EFI_TCP4_PROTOCOL EFI_TCP4_PROTOCOL;
34
35 typedef struct {
36 EFI_HANDLE InstanceHandle;
37 EFI_IPv4_ADDRESS LocalAddress;
38 UINT16 LocalPort;
39 EFI_IPv4_ADDRESS RemoteAddress;
40 UINT16 RemotePort;
41 } EFI_TCP4_SERVICE_POINT;
42
43 typedef struct {
44 EFI_HANDLE DriverHandle;
45 UINT32 ServiceCount;
46 EFI_TCP4_SERVICE_POINT Services[1];
47 } EFI_TCP4_VARIABLE_DATA;
48
49 typedef struct {
50 BOOLEAN UseDefaultAddress;
51 EFI_IPv4_ADDRESS StationAddress;
52 EFI_IPv4_ADDRESS SubnetMask;
53 UINT16 StationPort;
54 EFI_IPv4_ADDRESS RemoteAddress;
55 UINT16 RemotePort;
56 BOOLEAN ActiveFlag;
57 } EFI_TCP4_ACCESS_POINT;
58
59 typedef struct {
60 UINT32 ReceiveBufferSize;
61 UINT32 SendBufferSize;
62 UINT32 MaxSynBackLog;
63 UINT32 ConnectionTimeout;
64 UINT32 DataRetries;
65 UINT32 FinTimeout;
66 UINT32 TimeWaitTimeout;
67 UINT32 KeepAliveProbes;
68 UINT32 KeepAliveTime;
69 UINT32 KeepAliveInterval;
70 BOOLEAN EnableNagle;
71 BOOLEAN EnableTimeStamp;
72 BOOLEAN EnableWindowScaling;
73 BOOLEAN EnableSelectiveAck;
74 BOOLEAN EnablePathMtuDiscovery;
75 } EFI_TCP4_OPTION;
76
77 typedef struct {
78 //
79 // I/O parameters
80 //
81 UINT8 TypeOfService;
82 UINT8 TimeToLive;
83
84 //
85 // Access Point
86 //
87 EFI_TCP4_ACCESS_POINT AccessPoint;
88
89 //
90 // TCP Control Options
91 //
92 EFI_TCP4_OPTION *ControlOption;
93 } EFI_TCP4_CONFIG_DATA;
94
95 typedef enum {
96 Tcp4StateClosed = 0,
97 Tcp4StateListen = 1,
98 Tcp4StateSynSent = 2,
99 Tcp4StateSynReceived = 3,
100 Tcp4StateEstablished = 4,
101 Tcp4StateFinWait1 = 5,
102 Tcp4StateFinWait2 = 6,
103 Tcp4StateClosing = 7,
104 Tcp4StateTimeWait = 8,
105 Tcp4StateCloseWait = 9,
106 Tcp4StateLastAck = 10
107 } EFI_TCP4_CONNECTION_STATE;
108
109 typedef struct {
110 EFI_EVENT Event;
111 EFI_STATUS Status;
112 } EFI_TCP4_COMPLETION_TOKEN;
113
114 typedef struct {
115 EFI_TCP4_COMPLETION_TOKEN CompletionToken;
116 } EFI_TCP4_CONNECTION_TOKEN;
117
118 typedef struct {
119 EFI_TCP4_COMPLETION_TOKEN CompletionToken;
120 EFI_HANDLE NewChildHandle;
121 } EFI_TCP4_LISTEN_TOKEN;
122
123 typedef struct {
124 UINT32 FragmentLength;
125 VOID *FragmentBuffer;
126 } EFI_TCP4_FRAGMENT_DATA;
127
128 typedef struct {
129 BOOLEAN UrgentFlag;
130 UINT32 DataLength;
131 UINT32 FragmentCount;
132 EFI_TCP4_FRAGMENT_DATA FragmentTable[1];
133 } EFI_TCP4_RECEIVE_DATA;
134
135 typedef struct {
136 BOOLEAN Push;
137 BOOLEAN Urgent;
138 UINT32 DataLength;
139 UINT32 FragmentCount;
140 EFI_TCP4_FRAGMENT_DATA FragmentTable[1];
141 } EFI_TCP4_TRANSMIT_DATA;
142
143 typedef struct {
144 EFI_TCP4_COMPLETION_TOKEN CompletionToken;
145 union {
146 EFI_TCP4_RECEIVE_DATA *RxData;
147 EFI_TCP4_TRANSMIT_DATA *TxData;
148 } Packet;
149 } EFI_TCP4_IO_TOKEN;
150
151 typedef struct {
152 EFI_TCP4_COMPLETION_TOKEN CompletionToken;
153 BOOLEAN AbortOnClose;
154 } EFI_TCP4_CLOSE_TOKEN;
155
156 //
157 // Interface definition for TCP4 protocol
158 //
159
160 /**
161 Get the current operational status.
162
163 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
164 @param Tcp4State Pointer to the buffer to receive the current TCP state.
165 @param Tcp4ConfigData Pointer to the buffer to receive the current TCP configuration.
166 @param Ip4ModeData Pointer to the buffer to receive the current IPv4 configuration
167 data used by the TCPv4 instance.
168 @param MnpConfigData Pointer to the buffer to receive the current MNP configuration
169 data used indirectly by the TCPv4 instance.
170 @param SnpModeData Pointer to the buffer to receive the current SNP configuration
171 data used indirectly by the TCPv4 instance.
172
173 @retval EFI_SUCCESS The mode data was read.
174 @retval EFI_INVALID_PARAMETER This is NULL.
175 @retval EFI_NOT_STARTED No configuration data is available because this instance hasn't
176 been started.
177
178 **/
179 typedef
180 EFI_STATUS
181 (EFIAPI *EFI_TCP4_GET_MODE_DATA) (
182 IN CONST EFI_TCP4_PROTOCOL *This,
183 OUT EFI_TCP4_CONNECTION_STATE *Tcp4State OPTIONAL,
184 OUT EFI_TCP4_CONFIG_DATA *Tcp4ConfigData OPTIONAL,
185 OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL,
186 OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
187 OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
188 )
189 ;
190
191 /**
192 Initialize or brutally reset the operational parameters for this EFI TCPv4 instance.
193
194 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
195 @param Tcp4ConfigData Pointer to the configure data to configure the instance.
196
197 @retval EFI_SUCCESS The operational settings are set, changed, or reset
198 successfully.
199 @retval EFI_INVALID_PARAMETER Some parameter is invalid.
200 @retval EFI_NO_MAPPING When using a default address, configuration (through
201 DHCP, BOOTP, RARP, etc.) is not finished yet.
202 @retval EFI_ACCESS_DENIED Configuring TCP instance when it is configured without
203 calling Configure() with NULL to reset it.
204 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
205 @retval EFI_UNSUPPORTED One or more of the control options are not supported in
206 the implementation.
207 @retval EFI_OUT_OF_RESOURCES Could not allocate enough system resources when
208 executing Configure().
209
210 **/
211 typedef
212 EFI_STATUS
213 (EFIAPI *EFI_TCP4_CONFIGURE) (
214 IN EFI_TCP4_PROTOCOL *This,
215 IN EFI_TCP4_CONFIG_DATA *TcpConfigData OPTIONAL
216 )
217 ;
218
219
220 /**
221 Add or delete a route entry to the route table
222
223 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
224 @param DeleteRoute Set it to TRUE to delete this route from the routing table. Set it to
225 FALSE to add this route to the routing table.
226 DestinationAddress and SubnetMask are used as the
227 keywords to search route entry.
228 @param SubnetAddress The destination network.
229 @param SubnetMask The subnet mask of the destination network.
230 @param GatewayAddress The gateway address for this route. It must be on the same
231 subnet with the station address unless a direct route is specified.
232
233 @retval EFI_SUCCESS The operation completed successfully.
234 @retval EFI_NOT_STARTED The EFI TCPv4 Protocol instance has not been configured.
235 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
236 RARP, etc.) is not finished yet.
237 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
238 - This is NULL.
239 - SubnetAddress is NULL.
240 - SubnetMask is NULL.
241 - GatewayAddress is NULL.
242 - *SubnetAddress is not NULL a valid subnet address.
243 - *SubnetMask is not a valid subnet mask.
244 - *GatewayAddress is not a valid unicast IP address or it
245 is not in the same subnet.
246 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to add the entry to the
247 routing table.
248 @retval EFI_NOT_FOUND This route is not in the routing table.
249 @retval EFI_ACCESS_DENIED The route is already defined in the routing table.
250 @retval EFI_UNSUPPORTED The TCP driver does not support this operation.
251
252 **/
253 typedef
254 EFI_STATUS
255 (EFIAPI *EFI_TCP4_ROUTES) (
256 IN EFI_TCP4_PROTOCOL *This,
257 IN BOOLEAN DeleteRoute,
258 IN EFI_IPv4_ADDRESS *SubnetAddress,
259 IN EFI_IPv4_ADDRESS *SubnetMask,
260 IN EFI_IPv4_ADDRESS *GatewayAddress
261 )
262 ;
263
264 /**
265 Initiate a nonblocking TCP connection request for an active TCP instance.
266
267 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
268 @param ConnectionToken Pointer to the connection token to return when the TCP three
269 way handshake finishes.
270
271 @retval EFI_SUCCESS The connection request is successfully initiated and the state
272 - of this TCPv4 instance has been changed to
273 - Tcp4StateSynSent.
274 @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured.
275 @retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE:
276 - This instance is not configured as an active one.
277 - This instance is not in Tcp4StateClosed state.
278 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
279 - This is NULL.
280 - ConnectionToken is NULL.
281 - ConnectionToken->CompletionToken.Event is NULL.
282 @retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resource to initiate the activeopen.
283 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
284
285 **/
286 typedef
287 EFI_STATUS
288 (EFIAPI *EFI_TCP4_CONNECT) (
289 IN EFI_TCP4_PROTOCOL *This,
290 IN EFI_TCP4_CONNECTION_TOKEN *ConnectionToken
291 )
292 ;
293
294
295 /**
296 Listen on the passive instance to accept an incoming connection request. This is a nonblocking operation.
297
298 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
299 @param ListenToken Pointer to the listen token to return when operation finishes.
300
301 @retval EFI_SUCCESS The listen token has been queued successfully.
302 @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured.
303 @retval EFI_ACCESS_DENIED One or more of the following are TRUE:
304 - This instance is not a passive instance.
305 - This instance is not in Tcp4StateListen state.
306 - The same listen token has already existed in the listen
307 token queue of this TCP instance.
308 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
309 - This is NULL.
310 - ListenToken is NULL.
311 - ListentToken->CompletionToken.Event is NULL.
312 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
313 @retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error.
314
315 **/
316 typedef
317 EFI_STATUS
318 (EFIAPI *EFI_TCP4_ACCEPT) (
319 IN EFI_TCP4_PROTOCOL *This,
320 IN EFI_TCP4_LISTEN_TOKEN *ListenToken
321 )
322 ;
323
324 /**
325 Queues outgoing data into the transmit queue.
326
327 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
328 @param Token Pointer to the completion token to queue to the transmit queue.
329
330 @retval EFI_SUCCESS The data has been queued for transmission.
331 @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured.
332 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
333 RARP, etc.) is not finished yet.
334 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
335 - This is NULL.
336 - Token is NULL.
337 - Token->CompletionToken.Event is NULL.
338 - Token->Packet.TxData is NULL L.
339 - Token->Packet.FragmentCount is zero.
340 - Token->Packet.DataLength is not equal to the sum of fragment lengths.
341 @retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
342 - A transmit completion token with the same Token->CompletionToken.Event
343 was already in the transmission queue.
344 - The current instance is in Tcp4StateClosed state.
345 - The current instance is a passive one and it is in
346 Tcp4StateListen state.
347 - User has called Close() to disconnect this connection.
348 @retval EFI_NOT_READY The completion token could not be queued because the
349 transmit queue is full.
350 @retval EFI_OUT_OF_RESOURCES Could not queue the transmit data because of resource
351 shortage.
352 @retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or address.
353
354 **/
355 typedef
356 EFI_STATUS
357 (EFIAPI *EFI_TCP4_TRANSMIT) (
358 IN EFI_TCP4_PROTOCOL *This,
359 IN EFI_TCP4_IO_TOKEN *Token
360 )
361 ;
362
363
364 /**
365 Places an asynchronous receive request into the receiving queue.
366
367 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
368 @param Token Pointer to a token that is associated with the receive data
369 descriptor.
370
371 @retval EFI_SUCCESS The receive completion token was cached.
372 @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured.
373 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP,
374 etc.) is not finished yet.
375 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
376 - This is NULL.
377 - Token is NULL.
378 - Token->CompletionToken.Event is NULL.
379 - Token->Packet.RxData is NULL.
380 - Token->Packet.RxData->DataLength is 0.
381 - The Token->Packet.RxData->DataLength is not
382 the sum of all FragmentBuffer length in FragmentTable.
383 @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of
384 system resources (usually memory).
385 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
386 @retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
387 - A receive completion token with the same Token-
388 >CompletionToken.Event was already in the receive
389 queue.
390 - The current instance is in Tcp4StateClosed state.
391 - The current instance is a passive one and it is in
392 Tcp4StateListen state.
393 - User has called Close() to disconnect this connection.
394 @retval EFI_CONNECTION_FIN The communication peer has closed the connection and there is
395 no any buffered data in the receive buffer of this instance.
396 @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
397
398 **/
399 typedef
400 EFI_STATUS
401 (EFIAPI *EFI_TCP4_RECEIVE) (
402 IN EFI_TCP4_PROTOCOL *This,
403 IN EFI_TCP4_IO_TOKEN *Token
404 )
405 ;
406
407 /**
408 Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a
409 nonblocking operation.
410
411 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
412 @param CloseToken Pointer to the close token to return when operation finishes.
413
414 @retval EFI_SUCCESS The Close() is called successfully.
415 @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured.
416 @retval EFI_ACCESS_DENIED One or more of the following are TRUE:
417 - Configure() has been called with
418 TcpConfigData set to NULL and this function has
419 not returned.
420 - Previous Close() call on this instance has not
421 finished.
422 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
423 - This is NULL.
424 - CloseToken is NULL.
425 - CloseToken->CompletionToken.Event is NULL.
426 @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
427 @retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error.
428
429 **/
430 typedef
431 EFI_STATUS
432 (EFIAPI *EFI_TCP4_CLOSE) (
433 IN EFI_TCP4_PROTOCOL *This,
434 IN EFI_TCP4_CLOSE_TOKEN *CloseToken
435 )
436 ;
437
438 /**
439 Abort an asynchronous connection, listen, transmission or receive request.
440
441 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
442 @param Token Pointer to a token that has been issued by
443 EFI_TCP4_PROTOCOL.Connect(),
444 EFI_TCP4_PROTOCOL.Accept(),
445 EFI_TCP4_PROTOCOL.Transmit() or
446 EFI_TCP4_PROTOCOL.Receive(). If NULL, all pending
447 tokens issued by above four functions will be aborted. Type
448 EFI_TCP4_COMPLETION_TOKEN is defined in
449 EFI_TCP4_PROTOCOL.Connect().
450
451 @retval EFI_SUCCESS Incoming or outgoing data was processed.
452 @retval EFI_INVALID_PARAMETER This is NULL.
453 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
454 @retval EFI_NOT_READY No incoming or outgoing data is processed.
455 @retval EFI_TIMEOUT Data was dropped out of the transmission or receive queue.
456 Consider increasing the polling rate.
457
458 **/
459 typedef
460 EFI_STATUS
461 (EFIAPI *EFI_TCP4_CANCEL) (
462 IN EFI_TCP4_PROTOCOL *This,
463 IN EFI_TCP4_COMPLETION_TOKEN *Token OPTIONAL
464 )
465 ;
466
467
468 /**
469 Poll to receive incoming data and transmit outgoing segments.
470
471 @param This Pointer to the EFI_TCP4_PROTOCOL instance.
472
473 @retval EFI_SUCCESS Incoming or outgoing data was processed.
474 @retval EFI_INVALID_PARAMETER This is NULL.
475 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
476 @retval EFI_NOT_READY No incoming or outgoing data is processed.
477 @retval EFI_TIMEOUT Data was dropped out of the transmission or receive queue.
478 Consider increasing the polling rate.
479
480 **/
481 typedef
482 EFI_STATUS
483 (EFIAPI *EFI_TCP4_POLL) (
484 IN EFI_TCP4_PROTOCOL *This
485 )
486 ;
487
488 struct _EFI_TCP4_PROTOCOL {
489 EFI_TCP4_GET_MODE_DATA GetModeData;
490 EFI_TCP4_CONFIGURE Configure;
491 EFI_TCP4_ROUTES Routes;
492 EFI_TCP4_CONNECT Connect;
493 EFI_TCP4_ACCEPT Accept;
494 EFI_TCP4_TRANSMIT Transmit;
495 EFI_TCP4_RECEIVE Receive;
496 EFI_TCP4_CLOSE Close;
497 EFI_TCP4_CANCEL Cancel;
498 EFI_TCP4_POLL Poll;
499 };
500
501 #define EFI_CONNECTION_FIN EFIERR (104)
502 #define EFI_CONNECTION_RESET EFIERR (105)
503 #define EFI_CONNECTION_REFUSED EFIERR (106)
504
505 extern EFI_GUID gEfiTcp4ServiceBindingProtocolGuid;
506 extern EFI_GUID gEfiTcp4ProtocolGuid;
507
508 #endif