From a88c31639bb24c73383a4528a5b77066e805148b Mon Sep 17 00:00:00 2001 From: lpleahy Date: Fri, 30 Sep 2011 23:02:35 +0000 Subject: Update the sockets library code * Passes conformance and functional tests. * Builds with GCC 4.4 compiler. Signed-off by: lpleahy git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12497 6f19259b-4bc3-4df7-8a09-765794883524 --- StdLib/Include/Protocol/EfiSocket.h | 332 +++++++++++++++++++----------------- 1 file changed, 178 insertions(+), 154 deletions(-) (limited to 'StdLib/Include/Protocol/EfiSocket.h') diff --git a/StdLib/Include/Protocol/EfiSocket.h b/StdLib/Include/Protocol/EfiSocket.h index e9e4604048..2664f01bdb 100644 --- a/StdLib/Include/Protocol/EfiSocket.h +++ b/StdLib/Include/Protocol/EfiSocket.h @@ -27,6 +27,9 @@ // Data Types //------------------------------------------------------------------------------ +/** +EfiSocketLib (SocketDxe) interface +**/ typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL; /** @@ -45,11 +48,11 @@ EFI_STATUS // Data //------------------------------------------------------------------------------ -extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; -extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; +extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; ///< Constructor address for EslSocketLib +extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; ///< Destructor address for EslSocketLib -extern EFI_GUID gEfiSocketProtocolGuid; -extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; +extern EFI_GUID gEfiSocketProtocolGuid; ///< Socket protocol GUID +extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; ///< Socket layer service binding protocol GUID //------------------------------------------------------------------------------ // Socket API @@ -58,11 +61,16 @@ extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; /** Accept a network connection. - The SocketAccept routine waits for a network connection to the socket. - It is able to return the remote network address to the caller if - requested. + This routine calls the network specific layer to remove the next + connection from the FIFO. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::accept calls this routine to poll for a network + connection to the socket. When a connection is available + this routine returns the ::EFI_SOCKET_PROTOCOL structure address + associated with the new socket and the remote network address + if requested. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] pSockAddr Address of a buffer to receive the remote network address. @@ -71,8 +79,9 @@ extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; On output specifies the length of the remote network address. - @param [out] ppSocketProtocol Address of a buffer to receive the socket protocol - instance associated with the new socket. + @param [out] ppSocketProtocol Address of a buffer to receive the + ::EFI_SOCKET_PROTOCOL instance + associated with the new socket. @param [out] pErrno Address to receive the errno value upon completion. @@ -93,11 +102,13 @@ EFI_STATUS /** Bind a name to a socket. - The ::SocketBind routine connects a name to a socket on the local machine. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls the network specific layer to save the network + address of the local connection point. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::bind routine calls this routine to connect a name + (network address and port) to a socket on the local machine. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] pSockAddr Address of a sockaddr structure that contains the connection point on the local machine. An IPv4 address @@ -128,9 +139,14 @@ EFI_STATUS /** Determine if the socket is closed - Reverses the operations of the ::SocketAllocate() routine. + This routine checks the state of the socket to determine if + the network specific layer has completed the close operation. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::close routine polls this routine to determine when the + close operation is complete. The close operation needs to + reverse the operations of the ::EslSocketAllocate routine. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS Socket successfully closed @@ -149,11 +165,19 @@ EFI_STATUS /** Start the close operation on the socket - Start closing the socket by closing all of the ports. Upon - completion, the ::pfnClosePoll() routine finishes closing the - socket. + This routine calls the network specific layer to initiate the + close state machine. This routine then calls the network + specific layer to determine if the close state machine has gone + to completion. The result from this poll is returned to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::close routine calls this routine to start the close + operation which reverses the operations of the + ::EslSocketAllocate routine. The close routine then polls + the ::EslSocketClosePoll routine to determine when the + socket is closed. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] bCloseNow Boolean to control close behavior @param [out] pErrno Address to receive the errno value upon completion. @@ -174,35 +198,23 @@ EFI_STATUS /** Connect to a remote system via the network. - The ::Connect routine attempts to establish a connection to a - socket on the local or remote system using the specified address. - The - POSIX - documentation is available online. - - There are three states associated with a connection: - - In the "Not connected" state, calls to ::connect start the connection - processing and update the state to "Connection in progress". During - the "Connection in progress" state, connect polls for connection completion - and moves the state to "Connected" after the connection is established. - Note that these states are only visible when the file descriptor is marked - with O_NONBLOCK. Also, the POLL_WRITE bit is set when the connection - completes and may be used by poll or select as an indicator to call - connect again. + This routine calls the network specific layer to establish + the remote system address and establish the connection to + the remote system. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::connect routine calls this routine to establish a + connection with the specified remote system. This routine + is designed to be polled by the connect routine for completion + of the network connection. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] pSockAddr Network address of the remote system. - + @param [in] SockAddrLength Length in bytes of the network address. - + @param [out] pErrno Address to receive the errno value upon completion. - + @retval EFI_SUCCESS The connection was successfully established. @retval EFI_NOT_READY The connection is in progress, call this routine again. @retval Others The connection attempt failed. @@ -220,8 +232,14 @@ EFI_STATUS /** Get the local address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the network + address of the local host connection point. + The ::getsockname routine calls this routine to obtain the network + address associated with the local host connection point. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. + @param [out] pAddress Network address to receive the local system address @param [in,out] pAddressLength Length of the local network address structure @@ -243,8 +261,14 @@ EFI_STATUS /** Get the peer address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the remote + system connection point. + The ::getpeername routine calls this routine to obtain the network + address of the remote connection point. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. + @param [out] pAddress Network address to receive the remote system address @param [in,out] pAddressLength Length of the remote network address structure @@ -266,12 +290,16 @@ EFI_STATUS /** Establish the known port to listen for network connections. - The ::SocketAisten routine places the port into a state that enables connection - attempts. Connections are placed into FIFO order in a queue to be serviced - by the application. The application calls the ::SocketAccept routine to remove - the next connection from the queue and get the associated socket. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls into the network protocol layer to establish + a handler that is called upon connection completion. The handler + is responsible for inserting the connection into the FIFO. + + The ::listen routine indirectly calls this routine to place the + socket into a state that enables connection attempts. Connections + are placed in a FIFO that is serviced by the application. The + application calls the ::accept (::EslSocketAccept) routine to + remove the next connection from the FIFO and get the associated + socket and address. @param [in] pSocketProtocol Address of the socket protocol structure. @@ -297,11 +325,13 @@ EFI_STATUS /** Get the socket options - Retrieve the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. + + The ::getsockopt routine calls this routine to retrieve the + socket options one at a time by name. - @param [in] pSocketProtocol Address of the socket protocol structure. + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] level Option protocol level @param [in] OptionName Name of the option @param [out] pOptionValue Buffer to receive the option value @@ -326,18 +356,20 @@ EFI_STATUS /** Set the socket options - Adjust the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::setsockopt routine calls this routine to adjust the socket + options one at a time by name. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] level Option protocol level @param [in] OptionName Name of the option @param [in] pOptionValue Buffer containing the option value @param [in] OptionLength Length of the buffer in bytes @param [out] pErrno Address to receive the errno value upon completion. - @retval EFI_SUCCESS - Socket data successfully received + @retval EFI_SUCCESS - Option successfully set **/ typedef @@ -354,10 +386,14 @@ EFI_STATUS /** Poll a socket for pending activity. - The SocketPoll routine checks a socket for pending activity associated - with the event mask. Activity is returned in the detected event buffer. + This routine builds a detected event mask which is returned to + the caller in the buffer provided. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::poll routine calls this routine to determine if the socket + needs to be serviced as a result of connection, error, receive or + transmit activity. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] Events Events of interest for this socket @@ -381,19 +417,22 @@ EFI_STATUS /** Receive data from a network connection. - The ::recv routine waits for receive data from a remote network - connection. The - POSIX - documentation is available online. + This routine calls the network specific routine to remove the + next portion of data from the receive queue and return it to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::recvfrom routine calls this routine to determine if any data + is received from the remote system. Note that the other routines + ::recv and ::read are layered on top of ::recvfrom. + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. + @param [in] Flags Message control flags - + @param [in] BufferLength Length of the the buffer - + @param [in] pBuffer Address of a buffer to receive the data. - + @param [in] pDataLength Number of received data bytes in the buffer. @param [out] pAddress Network address to receive the remote system address @@ -418,54 +457,19 @@ EFI_STATUS IN int * pErrno ); -/** - Send data using a network connection. - - The SocketTransmit routine queues the data for transmission to the - remote network connection. - - @param [in] pSocketProtocol Address of the socket protocol structure. - - @param [in] Flags Message control flags - - @param [in] BufferLength Length of the the buffer - - @param [in] pBuffer Address of a buffer containing the data to send - - @param [in] pDataLength Address to receive the number of data bytes sent - - @param [in] pAddress Network address of the remote system address - - @param [in] AddressLength Length of the remote network address structure - - @param [out] pErrno Address to receive the errno value upon completion. - - @retval EFI_SUCCESS - Socket data successfully queued for transmission - - **/ -typedef -EFI_STATUS -(* PFN_SEND) ( - IN EFI_SOCKET_PROTOCOL * pSocketProtocol, - IN int Flags, - IN size_t BufferLength, - IN CONST UINT8 * pBuffer, - OUT size_t * pDataLength, - IN const struct sockaddr * pAddress, - IN socklen_t AddressLength, - IN int * pErrno - ); - /** Shutdown the socket receive and transmit operations - The SocketShutdown routine stops the socket receive and transmit - operations. + This routine sets a flag to stop future transmissions and calls + the network specific layer to cancel the pending receive operation. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::shutdown routine calls this routine to stop receive and transmit + operations on the socket. + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. + @param [in] How Which operations to stop - + @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket operations successfully shutdown @@ -482,40 +486,18 @@ EFI_STATUS /** Initialize an endpoint for network communication. - The ::Socket routine initializes the communication endpoint by providing - the support for the socket library function ::socket. The - POSIX - documentation for the socket routine is available online for reference. + This routine initializes the communication endpoint. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::socket routine calls this routine indirectly to create + the communication endpoint. + @param [in] pSocketProtocol Address of the socket protocol structure. @param [in] domain Select the family of protocols for the client or server - application. - - @param [in] type Specifies how to make the network connection. The following values - are supported: - - - @param [in] protocol Specifies the lower layer protocol to use. The following - values are supported: - - + application. See the ::socket documentation for values. + @param [in] type Specifies how to make the network connection. + See the ::socket documentation for values. + @param [in] protocol Specifies the lower layer protocol to use. + See the ::socket documentation for values. @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket successfully created @@ -534,6 +516,50 @@ EFI_STATUS IN int * pErrno ); +/** + Send data using a network connection. + + This routine calls the network specific layer to queue the data + for transmission. Eventually the buffer will reach the head of + the queue and will get transmitted over the network. For datagram + sockets there is no guarantee that the data reaches the application + running on the remote system. + + The ::sendto routine calls this routine to send data to the remote + system. Note that ::send and ::write are layered on top of ::sendto. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. + + @param [in] Flags Message control flags + + @param [in] BufferLength Length of the the buffer + + @param [in] pBuffer Address of a buffer containing the data to send + + @param [in] pDataLength Address to receive the number of data bytes sent + + @param [in] pAddress Network address of the remote system address + + @param [in] AddressLength Length of the remote network address structure + + @param [out] pErrno Address to receive the errno value upon completion. + + @retval EFI_SUCCESS - Socket data successfully queued for transmit + + **/ +typedef +EFI_STATUS +(* PFN_TRANSMIT) ( + IN EFI_SOCKET_PROTOCOL * pSocketProtocol, + IN int Flags, + IN size_t BufferLength, + IN CONST UINT8 * pBuffer, + OUT size_t * pDataLength, + IN const struct sockaddr * pAddress, + IN socklen_t AddressLength, + IN int * pErrno + ); + //------------------------------------------------------------------------------ // Socket Protocol //------------------------------------------------------------------------------ @@ -551,13 +577,13 @@ typedef struct _EFI_SOCKET_PROTOCOL { PFN_GET_LOCAL pfnGetLocal; ///< Get local address PFN_GET_PEER pfnGetPeer; ///< Get peer address PFN_LISTEN pfnListen; ///< Enable connection attempts on known port - PFN_POLL pfnPoll; ///< Poll for socket activity PFN_OPTION_GET pfnOptionGet; ///< Get socket options PFN_OPTION_SET pfnOptionSet; ///< Set socket options + PFN_POLL pfnPoll; ///< Poll for socket activity PFN_RECEIVE pfnReceive; ///< Receive data from a socket - PFN_SEND pfnSend; ///< Transmit data using the socket PFN_SHUTDOWN pfnShutdown; ///< Shutdown receive and transmit operations PFN_SOCKET pfnSocket; ///< Initialize the socket + PFN_TRANSMIT pfnTransmit; ///< Transmit data using the socket } GCC_EFI_SOCKET_PROTOCOL; //------------------------------------------------------------------------------ @@ -565,9 +591,7 @@ typedef struct _EFI_SOCKET_PROTOCOL { //------------------------------------------------------------------------------ /** - Non blocking version of accept. - - See ::accept + Non blocking version of ::accept. @param [in] s Socket file descriptor returned from ::socket. @@ -578,7 +602,7 @@ typedef struct _EFI_SOCKET_PROTOCOL { contains the length of the remote network address. @return This routine returns zero if successful and -1 when an error occurs. - In the case of an error, errno contains more details. + In the case of an error, ::errno contains more details. **/ int @@ -589,12 +613,12 @@ AcceptNB ( ); /** - Connect to the socket driver + Connect to the EFI socket library @param [in] ppSocketProtocol Address to receive the socket protocol address - @retval 0 Successfully returned the socket protocol - @retval other Value for errno + @return Value for ::errno, zero (0) indicates success. + **/ int EslServiceGetProtocol ( -- cgit v1.2.3