2 Definitions for the EFI Socket protocol.
4 Copyright (c) 2011, Intel Corporation
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
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.
15 #ifndef _EFI_SOCKET_H_
16 #define _EFI_SOCKET_H_
21 #include <netinet/in.h>
24 #include <sys/socket.h>
26 //------------------------------------------------------------------------------
28 //------------------------------------------------------------------------------
31 EfiSocketLib (SocketDxe) interface
33 typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL
;
36 Constructor/Destructor
38 @retval EFI_SUCCESS The operation was successful
43 (* PFN_ESL_xSTRUCTOR
) (
47 //------------------------------------------------------------------------------
49 //------------------------------------------------------------------------------
51 extern PFN_ESL_xSTRUCTOR mpfnEslConstructor
; ///< Constructor address for EslSocketLib
52 extern PFN_ESL_xSTRUCTOR mpfnEslDestructor
; ///< Destructor address for EslSocketLib
54 extern EFI_GUID gEfiSocketProtocolGuid
; ///< Socket protocol GUID
55 extern EFI_GUID gEfiSocketServiceBindingProtocolGuid
; ///< Socket layer service binding protocol GUID
57 //------------------------------------------------------------------------------
59 //------------------------------------------------------------------------------
62 Accept a network connection.
64 This routine calls the network specific layer to remove the next
65 connection from the FIFO.
67 The ::accept calls this routine to poll for a network
68 connection to the socket. When a connection is available
69 this routine returns the ::EFI_SOCKET_PROTOCOL structure address
70 associated with the new socket and the remote network address
73 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
75 @param [in] pSockAddr Address of a buffer to receive the remote
78 @param [in, out] pSockAddrLength Length in bytes of the address buffer.
79 On output specifies the length of the
80 remote network address.
82 @param [out] ppSocketProtocol Address of a buffer to receive the
83 ::EFI_SOCKET_PROTOCOL instance
84 associated with the new socket.
86 @param [out] pErrno Address to receive the errno value upon completion.
88 @retval EFI_SUCCESS New connection successfully created
89 @retval EFI_NOT_READY No connection is available
95 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
96 IN
struct sockaddr
* pSockAddr
,
97 IN OUT socklen_t
* pSockAddrLength
,
98 IN EFI_SOCKET_PROTOCOL
** ppSocketProtocol
,
103 Bind a name to a socket.
105 This routine calls the network specific layer to save the network
106 address of the local connection point.
108 The ::bind routine calls this routine to connect a name
109 (network address and port) to a socket on the local machine.
111 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
113 @param [in] pSockAddr Address of a sockaddr structure that contains the
114 connection point on the local machine. An IPv4 address
115 of INADDR_ANY specifies that the connection is made to
116 all of the network stacks on the platform. Specifying a
117 specific IPv4 address restricts the connection to the
118 network stack supporting that address. Specifying zero
119 for the port causes the network layer to assign a port
120 number from the dynamic range. Specifying a specific
121 port number causes the network layer to use that port.
123 @param [in] SockAddrLen Specifies the length in bytes of the sockaddr structure.
125 @param [out] pErrno Address to receive the errno value upon completion.
127 @retval EFI_SUCCESS - Socket successfully created
133 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
134 IN
const struct sockaddr
* pSockAddr
,
135 IN socklen_t SockAddrLength
,
140 Determine if the socket is closed
142 This routine checks the state of the socket to determine if
143 the network specific layer has completed the close operation.
145 The ::close routine polls this routine to determine when the
146 close operation is complete. The close operation needs to
147 reverse the operations of the ::EslSocketAllocate routine.
149 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
150 @param [out] pErrno Address to receive the errno value upon completion.
152 @retval EFI_SUCCESS Socket successfully closed
153 @retval EFI_NOT_READY Close still in progress
154 @retval EFI_ALREADY Close operation already in progress
155 @retval Other Failed to close the socket
161 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
166 Start the close operation on the socket
168 This routine calls the network specific layer to initiate the
169 close state machine. This routine then calls the network
170 specific layer to determine if the close state machine has gone
171 to completion. The result from this poll is returned to the
174 The ::close routine calls this routine to start the close
175 operation which reverses the operations of the
176 ::EslSocketAllocate routine. The close routine then polls
177 the ::EslSocketClosePoll routine to determine when the
180 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
181 @param [in] bCloseNow Boolean to control close behavior
182 @param [out] pErrno Address to receive the errno value upon completion.
184 @retval EFI_SUCCESS Socket successfully closed
185 @retval EFI_NOT_READY Close still in progress
186 @retval EFI_ALREADY Close operation already in progress
187 @retval Other Failed to close the socket
192 (* PFN_CLOSE_START
) (
193 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
194 IN BOOLEAN bCloseNow
,
199 Connect to a remote system via the network.
201 This routine calls the network specific layer to establish
202 the remote system address and establish the connection to
205 The ::connect routine calls this routine to establish a
206 connection with the specified remote system. This routine
207 is designed to be polled by the connect routine for completion
208 of the network connection.
210 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
212 @param [in] pSockAddr Network address of the remote system.
214 @param [in] SockAddrLength Length in bytes of the network address.
216 @param [out] pErrno Address to receive the errno value upon completion.
218 @retval EFI_SUCCESS The connection was successfully established.
219 @retval EFI_NOT_READY The connection is in progress, call this routine again.
220 @retval Others The connection attempt failed.
226 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
227 IN
const struct sockaddr
* pSockAddr
,
228 IN socklen_t SockAddrLength
,
233 Get the local address.
235 This routine calls the network specific layer to get the network
236 address of the local host connection point.
238 The ::getsockname routine calls this routine to obtain the network
239 address associated with the local host connection point.
241 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
243 @param [out] pAddress Network address to receive the local system address
245 @param [in,out] pAddressLength Length of the local network address structure
247 @param [out] pErrno Address to receive the errno value upon completion.
249 @retval EFI_SUCCESS - Local address successfully returned
255 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
256 OUT
struct sockaddr
* pAddress
,
257 IN OUT socklen_t
* pAddressLength
,
262 Get the peer address.
264 This routine calls the network specific layer to get the remote
265 system connection point.
267 The ::getpeername routine calls this routine to obtain the network
268 address of the remote connection point.
270 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
272 @param [out] pAddress Network address to receive the remote system address
274 @param [in,out] pAddressLength Length of the remote network address structure
276 @param [out] pErrno Address to receive the errno value upon completion.
278 @retval EFI_SUCCESS - Remote address successfully returned
284 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
285 OUT
struct sockaddr
* pAddress
,
286 IN OUT socklen_t
* pAddressLength
,
291 Establish the known port to listen for network connections.
293 This routine calls into the network protocol layer to establish
294 a handler that is called upon connection completion. The handler
295 is responsible for inserting the connection into the FIFO.
297 The ::listen routine indirectly calls this routine to place the
298 socket into a state that enables connection attempts. Connections
299 are placed in a FIFO that is serviced by the application. The
300 application calls the ::accept (::EslSocketAccept) routine to
301 remove the next connection from the FIFO and get the associated
304 @param [in] pSocketProtocol Address of the socket protocol structure.
306 @param [in] Backlog Backlog specifies the maximum FIFO depth for
307 the connections waiting for the application
308 to call accept. Connection attempts received
309 while the queue is full are refused.
311 @param [out] pErrno Address to receive the errno value upon completion.
313 @retval EFI_SUCCESS - Socket successfully created
314 @retval Other - Failed to enable the socket for listen
320 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
326 Get the socket options
328 This routine handles the socket level options and passes the
329 others to the network specific layer.
331 The ::getsockopt routine calls this routine to retrieve the
332 socket options one at a time by name.
334 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
335 @param [in] level Option protocol level
336 @param [in] OptionName Name of the option
337 @param [out] pOptionValue Buffer to receive the option value
338 @param [in,out] pOptionLength Length of the buffer in bytes,
339 upon return length of the option value in bytes
340 @param [out] pErrno Address to receive the errno value upon completion.
342 @retval EFI_SUCCESS - Socket data successfully received
348 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
351 OUT
void * __restrict pOptionValue
,
352 IN OUT socklen_t
* __restrict pOptionLength
,
357 Set the socket options
359 This routine handles the socket level options and passes the
360 others to the network specific layer.
362 The ::setsockopt routine calls this routine to adjust the socket
363 options one at a time by name.
365 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
366 @param [in] level Option protocol level
367 @param [in] OptionName Name of the option
368 @param [in] pOptionValue Buffer containing the option value
369 @param [in] OptionLength Length of the buffer in bytes
370 @param [out] pErrno Address to receive the errno value upon completion.
372 @retval EFI_SUCCESS - Option successfully set
378 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
381 IN CONST
void * pOptionValue
,
382 IN socklen_t OptionLength
,
387 Poll a socket for pending activity.
389 This routine builds a detected event mask which is returned to
390 the caller in the buffer provided.
392 The ::poll routine calls this routine to determine if the socket
393 needs to be serviced as a result of connection, error, receive or
396 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
398 @param [in] Events Events of interest for this socket
400 @param [in] pEvents Address to receive the detected events
402 @param [out] pErrno Address to receive the errno value upon completion.
404 @retval EFI_SUCCESS - Socket successfully polled
405 @retval EFI_INVALID_PARAMETER - When pEvents is NULL
411 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
418 Receive data from a network connection.
420 This routine calls the network specific routine to remove the
421 next portion of data from the receive queue and return it to the
424 The ::recvfrom routine calls this routine to determine if any data
425 is received from the remote system. Note that the other routines
426 ::recv and ::read are layered on top of ::recvfrom.
428 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
430 @param [in] Flags Message control flags
432 @param [in] BufferLength Length of the the buffer
434 @param [in] pBuffer Address of a buffer to receive the data.
436 @param [in] pDataLength Number of received data bytes in the buffer.
438 @param [out] pAddress Network address to receive the remote system address
440 @param [in,out] pAddressLength Length of the remote network address structure
442 @param [out] pErrno Address to receive the errno value upon completion.
444 @retval EFI_SUCCESS - Socket data successfully received
450 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
452 IN
size_t BufferLength
,
454 OUT
size_t * pDataLength
,
455 OUT
struct sockaddr
* pAddress
,
456 IN OUT socklen_t
* pAddressLength
,
461 Shutdown the socket receive and transmit operations
463 This routine sets a flag to stop future transmissions and calls
464 the network specific layer to cancel the pending receive operation.
466 The ::shutdown routine calls this routine to stop receive and transmit
467 operations on the socket.
469 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
471 @param [in] How Which operations to stop
473 @param [out] pErrno Address to receive the errno value upon completion.
475 @retval EFI_SUCCESS - Socket operations successfully shutdown
481 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
487 Initialize an endpoint for network communication.
489 This routine initializes the communication endpoint.
491 The ::socket routine calls this routine indirectly to create
492 the communication endpoint.
494 @param [in] pSocketProtocol Address of the socket protocol structure.
495 @param [in] domain Select the family of protocols for the client or server
496 application. See the ::socket documentation for values.
497 @param [in] type Specifies how to make the network connection.
498 See the ::socket documentation for values.
499 @param [in] protocol Specifies the lower layer protocol to use.
500 See the ::socket documentation for values.
501 @param [out] pErrno Address to receive the errno value upon completion.
503 @retval EFI_SUCCESS - Socket successfully created
504 @retval EFI_INVALID_PARAMETER - Invalid domain value, errno = EAFNOSUPPORT
505 @retval EFI_INVALID_PARAMETER - Invalid type value, errno = EINVAL
506 @retval EFI_INVALID_PARAMETER - Invalid protocol value, errno = EINVAL
512 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
520 Send data using a network connection.
522 This routine calls the network specific layer to queue the data
523 for transmission. Eventually the buffer will reach the head of
524 the queue and will get transmitted over the network. For datagram
525 sockets there is no guarantee that the data reaches the application
526 running on the remote system.
528 The ::sendto routine calls this routine to send data to the remote
529 system. Note that ::send and ::write are layered on top of ::sendto.
531 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
533 @param [in] Flags Message control flags
535 @param [in] BufferLength Length of the the buffer
537 @param [in] pBuffer Address of a buffer containing the data to send
539 @param [in] pDataLength Address to receive the number of data bytes sent
541 @param [in] pAddress Network address of the remote system address
543 @param [in] AddressLength Length of the remote network address structure
545 @param [out] pErrno Address to receive the errno value upon completion.
547 @retval EFI_SUCCESS - Socket data successfully queued for transmit
553 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
555 IN
size_t BufferLength
,
556 IN CONST UINT8
* pBuffer
,
557 OUT
size_t * pDataLength
,
558 IN
const struct sockaddr
* pAddress
,
559 IN socklen_t AddressLength
,
563 //------------------------------------------------------------------------------
565 //------------------------------------------------------------------------------
568 Socket protocol declaration
570 typedef struct _EFI_SOCKET_PROTOCOL
{
571 EFI_HANDLE SocketHandle
; ///< Handle for the socket
572 PFN_ACCEPT pfnAccept
; ///< Accept a network connection
573 PFN_BIND pfnBind
; ///< Bind a local address to the socket
574 PFN_CLOSE_POLL pfnClosePoll
; ///< Determine if the socket is closed
575 PFN_CLOSE_START pfnCloseStart
; ///< Start the close operation
576 PFN_CONNECT pfnConnect
; ///< Connect to a remote system
577 PFN_GET_LOCAL pfnGetLocal
; ///< Get local address
578 PFN_GET_PEER pfnGetPeer
; ///< Get peer address
579 PFN_LISTEN pfnListen
; ///< Enable connection attempts on known port
580 PFN_OPTION_GET pfnOptionGet
; ///< Get socket options
581 PFN_OPTION_SET pfnOptionSet
; ///< Set socket options
582 PFN_POLL pfnPoll
; ///< Poll for socket activity
583 PFN_RECEIVE pfnReceive
; ///< Receive data from a socket
584 PFN_SHUTDOWN pfnShutdown
; ///< Shutdown receive and transmit operations
585 PFN_SOCKET pfnSocket
; ///< Initialize the socket
586 PFN_TRANSMIT pfnTransmit
; ///< Transmit data using the socket
587 } GCC_EFI_SOCKET_PROTOCOL
;
589 //------------------------------------------------------------------------------
590 // Non-blocking routines
591 //------------------------------------------------------------------------------
594 Non blocking version of ::accept.
596 @param [in] s Socket file descriptor returned from ::socket.
598 @param [in] address Address of a buffer to receive the remote network address.
600 @param [in, out] address_len Address of a buffer containing the Length in bytes
601 of the remote network address buffer. Upon return,
602 contains the length of the remote network address.
604 @return This routine returns zero if successful and -1 when an error occurs.
605 In the case of an error, ::errno contains more details.
611 struct sockaddr
* address
,
612 socklen_t
* address_len
616 Free the socket resources
618 This releases the socket resources allocated by calling
619 EslServiceGetProtocol.
621 This routine is called from the ::close routine in BsdSocketLib
622 to release the socket resources.
624 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL
627 @return Value for ::errno, zero (0) indicates success.
631 EslServiceFreeProtocol (
632 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
636 Connect to the EFI socket library
638 @param [in] ppSocketProtocol Address to receive the socket protocol address
640 @return Value for ::errno, zero (0) indicates success.
644 EslServiceGetProtocol (
645 IN EFI_SOCKET_PROTOCOL
** ppSocketProtocol
648 //------------------------------------------------------------------------------
650 #endif // _EFI_SOCKET_H_