Tcp6.h

Last change on this file was 105670, checked in by vboxsync, 6 months ago
Devices/EFI/FirmwareNew: Merge edk2-stable-202405 and make it build on aarch64, bugref:4643
Property svn:eol-style set to `native`
File size: 37.3 KB

Line
1	/** @file
2	EFI TCPv6(Transmission Control Protocol version 6) Protocol Definition
3	The EFI TCPv6 Service Binding Protocol is used to locate EFI TCPv6 Protocol drivers to create
4	and destroy child of the driver to communicate with other host using TCP protocol.
5	The EFI TCPv6 Protocol provides services to send and receive data stream.
6
7	Copyright (c) 2008 - 2014, Intel Corporation. All rights reserved.<BR>
8	SPDX-License-Identifier: BSD-2-Clause-Patent
9
10	@par Revision Reference:
11	This Protocol is introduced in UEFI Specification 2.2
12
13	**/
14
15	#ifndef __EFI_TCP6_PROTOCOL_H__
16	#define __EFI_TCP6_PROTOCOL_H__
17
18	#include <Protocol/ManagedNetwork.h>
19	#include <Protocol/Ip6.h>
20
21	#define EFI_TCP6_SERVICE_BINDING_PROTOCOL_GUID \
22	{ \
23	0xec20eb79, 0x6c1a, 0x4664, {0x9a, 0x0d, 0xd2, 0xe4, 0xcc, 0x16, 0xd6, 0x64 } \
24	}
25
26	#define EFI_TCP6_PROTOCOL_GUID \
27	{ \
28	0x46e44855, 0xbd60, 0x4ab7, {0xab, 0x0d, 0xa6, 0x79, 0xb9, 0x44, 0x7d, 0x77 } \
29	}
30
31	typedef struct _EFI_TCP6_PROTOCOL EFI_TCP6_PROTOCOL;
32
33	///
34	/// EFI_TCP6_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more.
35	/// The definition in here is only present to provide backwards compatability.
36	///
37	typedef struct {
38	///
39	/// The EFI TCPv6 Protocol instance handle that is using this
40	/// address/port pair.
41	///
42	EFI_HANDLE InstanceHandle;
43	///
44	/// The local IPv6 address to which this TCP instance is bound. Set
45	/// to 0::/128, if this TCP instance is configured to listen on all
46	/// available source addresses.
47	///
48	EFI_IPv6_ADDRESS LocalAddress;
49	///
50	/// The local port number in host byte order.
51	///
52	UINT16 LocalPort;
53	///
54	/// The remote IPv6 address. It may be 0::/128 if this TCP instance is
55	/// not connected to any remote host.
56	///
57	EFI_IPv6_ADDRESS RemoteAddress;
58	///
59	/// The remote port number in host byte order. It may be zero if this
60	/// TCP instance is not connected to any remote host.
61	///
62	UINT16 RemotePort;
63	} EFI_TCP6_SERVICE_POINT;
64
65	///
66	/// EFI_TCP6_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more.
67	/// The definition in here is only present to provide backwards compatability.
68	///
69	typedef struct {
70	EFI_HANDLE DriverHandle; ///< The handle of the driver that creates this entry.
71	UINT32 ServiceCount; ///< The number of address/port pairs following this data structure.
72	EFI_TCP6_SERVICE_POINT Services[1]; ///< List of address/port pairs that are currently in use.
73	} EFI_TCP6_VARIABLE_DATA;
74
75	///
76	/// EFI_TCP6_ACCESS_POINT
77	///
78	typedef struct {
79	///
80	/// The local IP address assigned to this TCP instance. The EFI
81	/// TCPv6 driver will only deliver incoming packets whose
82	/// destination addresses exactly match the IP address. Set to zero to
83	/// let the underlying IPv6 driver choose a source address. If not zero
84	/// it must be one of the configured IP addresses in the underlying
85	/// IPv6 driver.
86	///
87	EFI_IPv6_ADDRESS StationAddress;
88	///
89	/// The local port number to which this EFI TCPv6 Protocol instance
90	/// is bound. If the instance doesn't care the local port number, set
91	/// StationPort to zero to use an ephemeral port.
92	///
93	UINT16 StationPort;
94	///
95	/// The remote IP address to which this EFI TCPv6 Protocol instance
96	/// is connected. If ActiveFlag is FALSE (i.e. a passive TCPv6
97	/// instance), the instance only accepts connections from the
98	/// RemoteAddress. If ActiveFlag is TRUE the instance will
99	/// connect to the RemoteAddress, i.e., outgoing segments will be
100	/// sent to this address and only segments from this address will be
101	/// delivered to the application. When ActiveFlag is FALSE, it
102	/// can be set to zero and means that incoming connection requests
103	/// from any address will be accepted.
104	///
105	EFI_IPv6_ADDRESS RemoteAddress;
106	///
107	/// The remote port to which this EFI TCPv6 Protocol instance
108	/// connects or from which connection request will be accepted by
109	/// this EFI TCPv6 Protocol instance. If ActiveFlag is FALSE it
110	/// can be zero and means that incoming connection request from
111	/// any port will be accepted. Its value can not be zero when
112	/// ActiveFlag is TRUE.
113	///
114	UINT16 RemotePort;
115	///
116	/// Set it to TRUE to initiate an active open. Set it to FALSE to
117	/// initiate a passive open to act as a server.
118	///
119	BOOLEAN ActiveFlag;
120	} EFI_TCP6_ACCESS_POINT;
121
122	///
123	/// EFI_TCP6_OPTION
124	///
125	typedef struct {
126	///
127	/// The size of the TCP receive buffer.
128	///
129	UINT32 ReceiveBufferSize;
130	///
131	/// The size of the TCP send buffer.
132	///
133	UINT32 SendBufferSize;
134	///
135	/// The length of incoming connect request queue for a passive
136	/// instance. When set to zero, the value is implementation specific.
137	///
138	UINT32 MaxSynBackLog;
139	///
140	/// The maximum seconds a TCP instance will wait for before a TCP
141	/// connection established. When set to zero, the value is
142	/// implementation specific.
143	///
144	UINT32 ConnectionTimeout;
145	///
146	/// The number of times TCP will attempt to retransmit a packet on
147	/// an established connection. When set to zero, the value is
148	/// implementation specific.
149	///
150	UINT32 DataRetries;
151	///
152	/// How many seconds to wait in the FIN_WAIT_2 states for a final
153	/// FIN flag before the TCP instance is closed. This timeout is in
154	/// effective only if the application has called Close() to
155	/// disconnect the connection completely. It is also called
156	/// FIN_WAIT_2 timer in other implementations. When set to zero,
157	/// it should be disabled because the FIN_WAIT_2 timer itself is
158	/// against the standard. The default value is 60.
159	///
160	UINT32 FinTimeout;
161	///
162	/// How many seconds to wait in TIME_WAIT state before the TCP
163	/// instance is closed. The timer is disabled completely to provide a
164	/// method to close the TCP connection quickly if it is set to zero. It
165	/// is against the related RFC documents.
166	///
167	UINT32 TimeWaitTimeout;
168	///
169	/// The maximum number of TCP keep-alive probes to send before
170	/// giving up and resetting the connection if no response from the
171	/// other end. Set to zero to disable keep-alive probe.
172	///
173	UINT32 KeepAliveProbes;
174	///
175	/// The number of seconds a connection needs to be idle before TCP
176	/// sends out periodical keep-alive probes. When set to zero, the
177	/// value is implementation specific. It should be ignored if keep-
178	/// alive probe is disabled.
179	///
180	UINT32 KeepAliveTime;
181	///
182	/// The number of seconds between TCP keep-alive probes after the
183	/// periodical keep-alive probe if no response. When set to zero, the
184	/// value is implementation specific. It should be ignored if keep-
185	/// alive probe is disabled.
186	///
187	UINT32 KeepAliveInterval;
188	///
189	/// Set it to TRUE to enable the Nagle algorithm as defined in
190	/// RFC896. Set it to FALSE to disable it.
191	///
192	BOOLEAN EnableNagle;
193	///
194	/// Set it to TRUE to enable TCP timestamps option as defined in
195	/// RFC7323. Set to FALSE to disable it.
196	///
197	BOOLEAN EnableTimeStamp;
198	///
199	/// Set it to TRUE to enable TCP window scale option as defined in
200	/// RFC7323. Set it to FALSE to disable it.
201	///
202	BOOLEAN EnableWindowScaling;
203	///
204	/// Set it to TRUE to enable selective acknowledge mechanism
205	/// described in RFC 2018. Set it to FALSE to disable it.
206	/// Implementation that supports SACK can optionally support
207	/// DSAK as defined in RFC 2883.
208	///
209	BOOLEAN EnableSelectiveAck;
210	///
211	/// Set it to TRUE to enable path MTU discovery as defined in
212	/// RFC 1191. Set to FALSE to disable it.
213	///
214	BOOLEAN EnablePathMtuDiscovery;
215	} EFI_TCP6_OPTION;
216
217	///
218	/// EFI_TCP6_CONFIG_DATA
219	///
220	typedef struct {
221	///
222	/// TrafficClass field in transmitted IPv6 packets.
223	///
224	UINT8 TrafficClass;
225	///
226	/// HopLimit field in transmitted IPv6 packets.
227	///
228	UINT8 HopLimit;
229	///
230	/// Used to specify TCP communication end settings for a TCP instance.
231	///
232	EFI_TCP6_ACCESS_POINT AccessPoint;
233	///
234	/// Used to configure the advance TCP option for a connection. If set
235	/// to NULL, implementation specific options for TCP connection will be used.
236	///
237	EFI_TCP6_OPTION *ControlOption;
238	} EFI_TCP6_CONFIG_DATA;
239
240	///
241	/// EFI_TCP6_CONNECTION_STATE
242	///
243	typedef enum {
244	Tcp6StateClosed = 0,
245	Tcp6StateListen = 1,
246	Tcp6StateSynSent = 2,
247	Tcp6StateSynReceived = 3,
248	Tcp6StateEstablished = 4,
249	Tcp6StateFinWait1 = 5,
250	Tcp6StateFinWait2 = 6,
251	Tcp6StateClosing = 7,
252	Tcp6StateTimeWait = 8,
253	Tcp6StateCloseWait = 9,
254	Tcp6StateLastAck = 10
255	} EFI_TCP6_CONNECTION_STATE;
256
257	///
258	/// EFI_TCP6_COMPLETION_TOKEN
259	/// is used as a common header for various asynchronous tokens.
260	///
261	typedef struct {
262	///
263	/// The Event to signal after request is finished and Status field is
264	/// updated by the EFI TCPv6 Protocol driver.
265	///
266	EFI_EVENT Event;
267	///
268	/// The result of the completed operation.
269	///
270	EFI_STATUS Status;
271	} EFI_TCP6_COMPLETION_TOKEN;
272
273	///
274	/// EFI_TCP6_CONNECTION_TOKEN
275	/// will be set if the active open succeeds or an unexpected
276	/// error happens.
277	///
278	typedef struct {
279	///
280	/// The Status in the CompletionToken will be set to one of
281	/// the following values if the active open succeeds or an unexpected
282	/// error happens:
283	/// EFI_SUCCESS: The active open succeeds and the instance's
284	/// state is Tcp6StateEstablished.
285	/// EFI_CONNECTION_RESET: The connect fails because the connection is reset
286	/// either by instance itself or the communication peer.
287	/// EFI_CONNECTION_REFUSED: The receiving or transmission operation fails because this
288	/// connection is refused.
289	/// EFI_ABORTED: The active open is aborted.
290	/// EFI_TIMEOUT: The connection establishment timer expires and
291	/// no more specific information is available.
292	/// EFI_NETWORK_UNREACHABLE: The active open fails because
293	/// an ICMP network unreachable error is received.
294	/// EFI_HOST_UNREACHABLE: The active open fails because an
295	/// ICMP host unreachable error is received.
296	/// EFI_PROTOCOL_UNREACHABLE: The active open fails
297	/// because an ICMP protocol unreachable error is received.
298	/// EFI_PORT_UNREACHABLE: The connection establishment
299	/// timer times out and an ICMP port unreachable error is received.
300	/// EFI_ICMP_ERROR: The connection establishment timer times
301	/// out and some other ICMP error is received.
302	/// EFI_DEVICE_ERROR: An unexpected system or network error occurred.
303	/// EFI_SECURITY_VIOLATION: The active open was failed because of IPSec policy check.
304	/// EFI_NO_MEDIA: There was a media error.
305	///
306	EFI_TCP6_COMPLETION_TOKEN CompletionToken;
307	} EFI_TCP6_CONNECTION_TOKEN;
308
309	///
310	/// EFI_TCP6_LISTEN_TOKEN
311	/// returns when list operation finishes.
312	///
313	typedef struct {
314	///
315	/// The Status in CompletionToken will be set to the
316	/// following value if accept finishes:
317	/// EFI_SUCCESS: A remote peer has successfully established a
318	/// connection to this instance. A new TCP instance has also been
319	/// created for the connection.
320	/// EFI_CONNECTION_RESET: The accept fails because the connection is reset either
321	/// by instance itself or communication peer.
322	/// EFI_ABORTED: The accept request has been aborted.
323	/// EFI_SECURITY_VIOLATION: The accept operation was failed because of IPSec policy check.
324	///
325	EFI_TCP6_COMPLETION_TOKEN CompletionToken;
326	EFI_HANDLE NewChildHandle;
327	} EFI_TCP6_LISTEN_TOKEN;
328
329	///
330	/// EFI_TCP6_FRAGMENT_DATA
331	/// allows multiple receive or transmit buffers to be specified. The
332	/// purpose of this structure is to provide scattered read and write.
333	///
334	typedef struct {
335	UINT32 FragmentLength; ///< Length of data buffer in the fragment.
336	VOID *FragmentBuffer; ///< Pointer to the data buffer in the fragment.
337	} EFI_TCP6_FRAGMENT_DATA;
338
339	///
340	/// EFI_TCP6_RECEIVE_DATA
341	/// When TCPv6 driver wants to deliver received data to the application,
342	/// it will pick up the first queued receiving token, update its
343	/// Token->Packet.RxData then signal the Token->CompletionToken.Event.
344	///
345	typedef struct {
346	///
347	/// Whether the data is urgent. When this flag is set, the instance is in
348	/// urgent mode.
349	///
350	BOOLEAN UrgentFlag;
351	///
352	/// When calling Receive() function, it is the byte counts of all
353	/// Fragmentbuffer in FragmentTable allocated by user.
354	/// When the token is signaled by TCPv6 driver it is the length of
355	/// received data in the fragments.
356	///
357	UINT32 DataLength;
358	///
359	/// Number of fragments.
360	///
361	UINT32 FragmentCount;
362	///
363	/// An array of fragment descriptors.
364	///
365	EFI_TCP6_FRAGMENT_DATA FragmentTable[1];
366	} EFI_TCP6_RECEIVE_DATA;
367
368	///
369	/// EFI_TCP6_TRANSMIT_DATA
370	/// The EFI TCPv6 Protocol user must fill this data structure before sending a packet.
371	/// The packet may contain multiple buffers in non-continuous memory locations.
372	///
373	typedef struct {
374	///
375	/// Push If TRUE, data must be transmitted promptly, and the PUSH bit in
376	/// the last TCP segment created will be set. If FALSE, data
377	/// transmission may be delayed to combine with data from
378	/// subsequent Transmit()s for efficiency.
379	///
380	BOOLEAN Push;
381	///
382	/// The data in the fragment table are urgent and urgent point is in
383	/// effect if TRUE. Otherwise those data are NOT considered urgent.
384	///
385	BOOLEAN Urgent;
386	///
387	/// Length of the data in the fragments.
388	///
389	UINT32 DataLength;
390	///
391	/// Number of fragments.
392	///
393	UINT32 FragmentCount;
394	///
395	/// An array of fragment descriptors.
396	///
397	EFI_TCP6_FRAGMENT_DATA FragmentTable[1];
398	} EFI_TCP6_TRANSMIT_DATA;
399
400	///
401	/// EFI_TCP6_IO_TOKEN
402	/// returns When transmission finishes or meets any unexpected error.
403	///
404	typedef struct {
405	///
406	/// When transmission finishes or meets any unexpected error it will
407	/// be set to one of the following values:
408	/// EFI_SUCCESS: The receiving or transmission operation
409	/// completes successfully.
410	/// EFI_CONNECTION_FIN: The receiving operation fails because the communication peer
411	/// has closed the connection and there is no more data in the
412	/// receive buffer of the instance.
413	/// EFI_CONNECTION_RESET: The receiving or transmission operation fails
414	/// because this connection is reset either by instance
415	/// itself or the communication peer.
416	/// EFI_ABORTED: The receiving or transmission is aborted.
417	/// EFI_TIMEOUT: The transmission timer expires and no more
418	/// specific information is available.
419	/// EFI_NETWORK_UNREACHABLE: The transmission fails
420	/// because an ICMP network unreachable error is received.
421	/// EFI_HOST_UNREACHABLE: The transmission fails because an
422	/// ICMP host unreachable error is received.
423	/// EFI_PROTOCOL_UNREACHABLE: The transmission fails
424	/// because an ICMP protocol unreachable error is received.
425	/// EFI_PORT_UNREACHABLE: The transmission fails and an
426	/// ICMP port unreachable error is received.
427	/// EFI_ICMP_ERROR: The transmission fails and some other
428	/// ICMP error is received.
429	/// EFI_DEVICE_ERROR: An unexpected system or network error occurs.
430	/// EFI_SECURITY_VIOLATION: The receiving or transmission
431	/// operation was failed because of IPSec policy check
432	/// EFI_NO_MEDIA: There was a media error.
433	///
434	EFI_TCP6_COMPLETION_TOKEN CompletionToken;
435	union {
436	///
437	/// When this token is used for receiving, RxData is a pointer to
438	/// EFI_TCP6_RECEIVE_DATA.
439	///
440	EFI_TCP6_RECEIVE_DATA *RxData;
441	///
442	/// When this token is used for transmitting, TxData is a pointer to
443	/// EFI_TCP6_TRANSMIT_DATA.
444	///
445	EFI_TCP6_TRANSMIT_DATA *TxData;
446	} Packet;
447	} EFI_TCP6_IO_TOKEN;
448
449	///
450	/// EFI_TCP6_CLOSE_TOKEN
451	/// returns when close operation finishes.
452	///
453	typedef struct {
454	///
455	/// When close finishes or meets any unexpected error it will be set
456	/// to one of the following values:
457	/// EFI_SUCCESS: The close operation completes successfully.
458	/// EFI_ABORTED: User called configure with NULL without close stopping.
459	/// EFI_SECURITY_VIOLATION: The close operation was failed because of IPSec policy check.
460	///
461	EFI_TCP6_COMPLETION_TOKEN CompletionToken;
462	///
463	/// Abort the TCP connection on close instead of the standard TCP
464	/// close process when it is set to TRUE. This option can be used to
465	/// satisfy a fast disconnect.
466	///
467	BOOLEAN AbortOnClose;
468	} EFI_TCP6_CLOSE_TOKEN;
469
470	/**
471	Get the current operational status.
472
473	The GetModeData() function copies the current operational settings of this EFI TCPv6
474	Protocol instance into user-supplied buffers. This function can also be used to retrieve
475	the operational setting of underlying drivers such as IPv6, MNP, or SNP.
476
477	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
478	@param[out] Tcp6State The buffer in which the current TCP state is returned.
479	@param[out] Tcp6ConfigData The buffer in which the current TCP configuration is returned.
480	@param[out] Ip6ModeData The buffer in which the current IPv6 configuration data used by
481	the TCP instance is returned.
482	@param[out] MnpConfigData The buffer in which the current MNP configuration data used
483	indirectly by the TCP instance is returned.
484	@param[out] SnpModeData The buffer in which the current SNP mode data used indirectly by
485	the TCP instance is returned.
486
487	@retval EFI_SUCCESS The mode data was read.
488	@retval EFI_NOT_STARTED No configuration data is available because this instance hasn't
489	been started.
490	@retval EFI_INVALID_PARAMETER This is NULL.
491
492	**/
493	typedef
494	EFI_STATUS
495	(EFIAPI *EFI_TCP6_GET_MODE_DATA)(
496	IN EFI_TCP6_PROTOCOL *This,
497	OUT EFI_TCP6_CONNECTION_STATE *Tcp6State OPTIONAL,
498	OUT EFI_TCP6_CONFIG_DATA *Tcp6ConfigData OPTIONAL,
499	OUT EFI_IP6_MODE_DATA *Ip6ModeData OPTIONAL,
500	OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
501	OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
502	);
503
504	/**
505	Initialize or brutally reset the operational parameters for this EFI TCPv6 instance.
506
507	The Configure() function does the following:
508	- Initialize this TCP instance, i.e., initialize the communication end settings and
509	specify active open or passive open for an instance.
510	- Reset this TCP instance brutally, i.e., cancel all pending asynchronous tokens, flush
511	transmission and receiving buffer directly without informing the communication peer.
512
513	No other TCPv6 Protocol operation except Poll() can be executed by this instance until
514	it is configured properly. For an active TCP instance, after a proper configuration it
515	may call Connect() to initiates the three-way handshake. For a passive TCP instance,
516	its state will transit to Tcp6StateListen after configuration, and Accept() may be
517	called to listen the incoming TCP connection requests. If Tcp6ConfigData is set to NULL,
518	the instance is reset. Resetting process will be done brutally, the state machine will
519	be set to Tcp6StateClosed directly, the receive queue and transmit queue will be flushed,
520	and no traffic is allowed through this instance.
521
522	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
523	@param[in] Tcp6ConfigData Pointer to the configure data to configure the instance.
524	If Tcp6ConfigData is set to NULL, the instance is reset.
525
526	@retval EFI_SUCCESS The operational settings are set, changed, or reset
527	successfully.
528	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
529	address for this instance, but no source address was available for
530	use.
531	@retval EFI_INVALID_PARAMETER One or more of the following conditions are TRUE:
532	- This is NULL.
533	- Tcp6ConfigData->AccessPoint.StationAddress is neither zero nor
534	one of the configured IP addresses in the underlying IPv6 driver.
535	- Tcp6ConfigData->AccessPoint.RemoteAddress isn't a valid unicast
536	IPv6 address.
537	- Tcp6ConfigData->AccessPoint.RemoteAddress is zero or
538	Tcp6ConfigData->AccessPoint.RemotePort is zero when
539	Tcp6ConfigData->AccessPoint.ActiveFlag is TRUE.
540	- A same access point has been configured in other TCP
541	instance properly.
542	@retval EFI_ACCESS_DENIED Configuring TCP instance when it is configured without
543	calling Configure() with NULL to reset it.
544	@retval EFI_UNSUPPORTED One or more of the control options are not supported in
545	the implementation.
546	@retval EFI_OUT_OF_RESOURCES Could not allocate enough system resources when
547	executing Configure().
548	@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
549
550	**/
551	typedef
552	EFI_STATUS
553	(EFIAPI *EFI_TCP6_CONFIGURE)(
554	IN EFI_TCP6_PROTOCOL *This,
555	IN EFI_TCP6_CONFIG_DATA *Tcp6ConfigData OPTIONAL
556	);
557
558	/**
559	Initiate a nonblocking TCP connection request for an active TCP instance.
560
561	The Connect() function will initiate an active open to the remote peer configured
562	in current TCP instance if it is configured active. If the connection succeeds or
563	fails due to any error, the ConnectionToken->CompletionToken.Event will be signaled
564	and ConnectionToken->CompletionToken.Status will be updated accordingly. This
565	function can only be called for the TCP instance in Tcp6StateClosed state. The
566	instance will transfer into Tcp6StateSynSent if the function returns EFI_SUCCESS.
567	If TCP three-way handshake succeeds, its state will become Tcp6StateEstablished,
568	otherwise, the state will return to Tcp6StateClosed.
569
570	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
571	@param[in] ConnectionToken Pointer to the connection token to return when the TCP three
572	way handshake finishes.
573
574	@retval EFI_SUCCESS The connection request is successfully initiated and the state of
575	this TCP instance has been changed to Tcp6StateSynSent.
576	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
577	@retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE:
578	- This instance is not configured as an active one.
579	- This instance is not in Tcp6StateClosed state.
580	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
581	- This is NULL.
582	- ConnectionToken is NULL.
583	- ConnectionToken->CompletionToken.Event is NULL.
584	@retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resource to initiate the active open.
585	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
586
587	**/
588	typedef
589	EFI_STATUS
590	(EFIAPI *EFI_TCP6_CONNECT)(
591	IN EFI_TCP6_PROTOCOL *This,
592	IN EFI_TCP6_CONNECTION_TOKEN *ConnectionToken
593	);
594
595	/**
596	Listen on the passive instance to accept an incoming connection request. This is a
597	nonblocking operation.
598
599	The Accept() function initiates an asynchronous accept request to wait for an incoming
600	connection on the passive TCP instance. If a remote peer successfully establishes a
601	connection with this instance, a new TCP instance will be created and its handle will
602	be returned in ListenToken->NewChildHandle. The newly created instance is configured
603	by inheriting the passive instance's configuration and is ready for use upon return.
604	The new instance is in the Tcp6StateEstablished state.
605
606	The ListenToken->CompletionToken.Event will be signaled when a new connection is
607	accepted, user aborts the listen or connection is reset.
608
609	This function only can be called when current TCP instance is in Tcp6StateListen state.
610
611	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
612	@param[in] ListenToken Pointer to the listen token to return when operation finishes.
613
614
615	@retval EFI_SUCCESS The listen token has been queued successfully.
616	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
617	@retval EFI_ACCESS_DENIED One or more of the following are TRUE:
618	- This instance is not a passive instance.
619	- This instance is not in Tcp6StateListen state.
620	- The same listen token has already existed in the listen
621	token queue of this TCP instance.
622	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
623	- This is NULL.
624	- ListenToken is NULL.
625	- ListentToken->CompletionToken.Event is NULL.
626	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
627	@retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error.
628
629	**/
630	typedef
631	EFI_STATUS
632	(EFIAPI *EFI_TCP6_ACCEPT)(
633	IN EFI_TCP6_PROTOCOL *This,
634	IN EFI_TCP6_LISTEN_TOKEN *ListenToken
635	);
636
637	/**
638	Queues outgoing data into the transmit queue.
639
640	The Transmit() function queues a sending request to this TCP instance along with the
641	user data. The status of the token is updated and the event in the token will be
642	signaled once the data is sent out or some error occurs.
643
644	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
645	@param[in] Token Pointer to the completion token to queue to the transmit queue.
646
647	@retval EFI_SUCCESS The data has been queued for transmission.
648	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
649	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a
650	source address for this instance, but no source address was
651	available for use.
652	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
653	- This is NULL.
654	- Token is NULL.
655	- Token->CompletionToken.Event is NULL.
656	- Token->Packet.TxData is NULL.
657	- Token->Packet.FragmentCount is zero.
658	- Token->Packet.DataLength is not equal to the sum of fragment lengths.
659	@retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE:
660	- A transmit completion token with the same Token->
661	CompletionToken.Event was already in the
662	transmission queue.
663	- The current instance is in Tcp6StateClosed state.
664	- The current instance is a passive one and it is in
665	Tcp6StateListen state.
666	- User has called Close() to disconnect this connection.
667	@retval EFI_NOT_READY The completion token could not be queued because the
668	transmit queue is full.
669	@retval EFI_OUT_OF_RESOURCES Could not queue the transmit data because of resource
670	shortage.
671	@retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or address.
672
673	**/
674	typedef
675	EFI_STATUS
676	(EFIAPI *EFI_TCP6_TRANSMIT)(
677	IN EFI_TCP6_PROTOCOL *This,
678	IN EFI_TCP6_IO_TOKEN *Token
679	);
680
681	/**
682	Places an asynchronous receive request into the receiving queue.
683
684	The Receive() function places a completion token into the receive packet queue. This
685	function is always asynchronous. The caller must allocate the Token->CompletionToken.Event
686	and the FragmentBuffer used to receive data. The caller also must fill the DataLength which
687	represents the whole length of all FragmentBuffer. When the receive operation completes, the
688	EFI TCPv6 Protocol driver updates the Token->CompletionToken.Status and Token->Packet.RxData
689	fields and the Token->CompletionToken.Event is signaled. If got data the data and its length
690	will be copied into the FragmentTable, at the same time the full length of received data will
691	be recorded in the DataLength fields. Providing a proper notification function and context
692	for the event will enable the user to receive the notification and receiving status. That
693	notification function is guaranteed to not be re-entered.
694
695	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
696	@param[in] Token Pointer to a token that is associated with the receive data
697	descriptor.
698
699	@retval EFI_SUCCESS The receive completion token was cached.
700	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
701	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
702	address for this instance, but no source address was available for use.
703	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
704	- This is NULL.
705	- Token is NULL.
706	- Token->CompletionToken.Event is NULL.
707	- Token->Packet.RxData is NULL.
708	- Token->Packet.RxData->DataLength is 0.
709	- The Token->Packet.RxData->DataLength is not the
710	sum of all FragmentBuffer length in FragmentTable.
711	@retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of
712	system resources (usually memory).
713	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
714	The EFI TCPv6 Protocol instance has been reset to startup defaults.
715	@retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
716	- A receive completion token with the same Token->CompletionToken.Event
717	was already in the receive queue.
718	- The current instance is in Tcp6StateClosed state.
719	- The current instance is a passive one and it is in
720	Tcp6StateListen state.
721	- User has called Close() to disconnect this connection.
722	@retval EFI_CONNECTION_FIN The communication peer has closed the connection and there is no
723	any buffered data in the receive buffer of this instance
724	@retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
725
726	**/
727	typedef
728	EFI_STATUS
729	(EFIAPI *EFI_TCP6_RECEIVE)(
730	IN EFI_TCP6_PROTOCOL *This,
731	IN EFI_TCP6_IO_TOKEN *Token
732	);
733
734	/**
735	Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a
736	nonblocking operation.
737
738	Initiate an asynchronous close token to TCP driver. After Close() is called, any buffered
739	transmission data will be sent by TCP driver and the current instance will have a graceful close
740	working flow described as RFC 793 if AbortOnClose is set to FALSE, otherwise, a rest packet
741	will be sent by TCP driver to fast disconnect this connection. When the close operation completes
742	successfully the TCP instance is in Tcp6StateClosed state, all pending asynchronous
743	operations are signaled and any buffers used for TCP network traffic are flushed.
744
745	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
746	@param[in] CloseToken Pointer to the close token to return when operation finishes.
747
748	@retval EFI_SUCCESS The Close() is called successfully.
749	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
750	@retval EFI_ACCESS_DENIED One or more of the following are TRUE:
751	- CloseToken or CloseToken->CompletionToken.Event is already in use.
752	- Previous Close() call on this instance has not finished.
753	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
754	- This is NULL.
755	- CloseToken is NULL.
756	- CloseToken->CompletionToken.Event is NULL.
757	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
758	@retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error.
759
760	**/
761	typedef
762	EFI_STATUS
763	(EFIAPI *EFI_TCP6_CLOSE)(
764	IN EFI_TCP6_PROTOCOL *This,
765	IN EFI_TCP6_CLOSE_TOKEN *CloseToken
766	);
767
768	/**
769	Abort an asynchronous connection, listen, transmission or receive request.
770
771	The Cancel() function aborts a pending connection, listen, transmit or
772	receive request.
773
774	If Token is not NULL and the token is in the connection, listen, transmission
775	or receive queue when it is being cancelled, its Token->Status will be set
776	to EFI_ABORTED and then Token->Event will be signaled.
777
778	If the token is not in one of the queues, which usually means that the
779	asynchronous operation has completed, EFI_NOT_FOUND is returned.
780
781	If Token is NULL all asynchronous token issued by Connect(), Accept(),
782	Transmit() and Receive() will be aborted.
783
784	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
785	@param[in] Token Pointer to a token that has been issued by
786	EFI_TCP6_PROTOCOL.Connect(),
787	EFI_TCP6_PROTOCOL.Accept(),
788	EFI_TCP6_PROTOCOL.Transmit() or
789	EFI_TCP6_PROTOCOL.Receive(). If NULL, all pending
790	tokens issued by above four functions will be aborted. Type
791	EFI_TCP6_COMPLETION_TOKEN is defined in
792	EFI_TCP_PROTOCOL.Connect().
793
794	@retval EFI_SUCCESS The asynchronous I/O request is aborted and Token->Event
795	is signaled.
796	@retval EFI_INVALID_PARAMETER This is NULL.
797	@retval EFI_NOT_STARTED This instance hasn't been configured.
798	@retval EFI_NOT_FOUND The asynchronous I/O request isn't found in the transmission or
799	receive queue. It has either completed or wasn't issued by
800	Transmit() and Receive().
801	@retval EFI_UNSUPPORTED The implementation does not support this function.
802
803	**/
804	typedef
805	EFI_STATUS
806	(EFIAPI *EFI_TCP6_CANCEL)(
807	IN EFI_TCP6_PROTOCOL *This,
808	IN EFI_TCP6_COMPLETION_TOKEN *Token OPTIONAL
809	);
810
811	/**
812	Poll to receive incoming data and transmit outgoing segments.
813
814	The Poll() function increases the rate that data is moved between the network
815	and application and can be called when the TCP instance is created successfully.
816	Its use is optional.
817
818	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
819
820	@retval EFI_SUCCESS Incoming or outgoing data was processed.
821	@retval EFI_INVALID_PARAMETER This is NULL.
822	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
823	@retval EFI_NOT_READY No incoming or outgoing data is processed.
824	@retval EFI_TIMEOUT Data was dropped out of the transmission or receive queue.
825	Consider increasing the polling rate.
826
827	**/
828	typedef
829	EFI_STATUS
830	(EFIAPI *EFI_TCP6_POLL)(
831	IN EFI_TCP6_PROTOCOL *This
832	);
833
834	///
835	/// EFI_TCP6_PROTOCOL
836	/// defines the EFI TCPv6 Protocol child to be used by any network drivers or
837	/// applications to send or receive data stream. It can either listen on a
838	/// specified port as a service or actively connect to remote peer as a client.
839	/// Each instance has its own independent settings.
840	///
841	struct _EFI_TCP6_PROTOCOL {
842	EFI_TCP6_GET_MODE_DATA GetModeData;
843	EFI_TCP6_CONFIGURE Configure;
844	EFI_TCP6_CONNECT Connect;
845	EFI_TCP6_ACCEPT Accept;
846	EFI_TCP6_TRANSMIT Transmit;
847	EFI_TCP6_RECEIVE Receive;
848	EFI_TCP6_CLOSE Close;
849	EFI_TCP6_CANCEL Cancel;
850	EFI_TCP6_POLL Poll;
851	};
852
853	extern EFI_GUID gEfiTcp6ServiceBindingProtocolGuid;
854	extern EFI_GUID gEfiTcp6ProtocolGuid;
855
856	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Protocol/Tcp6.h

Download in other formats: