// Data Types\r
//------------------------------------------------------------------------------\r
\r
+/**\r
+EfiSocketLib (SocketDxe) interface \r
+**/\r
typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL;\r
\r
/**\r
// Data\r
//------------------------------------------------------------------------------\r
\r
-extern PFN_ESL_xSTRUCTOR mpfnEslConstructor;\r
-extern PFN_ESL_xSTRUCTOR mpfnEslDestructor;\r
+extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; ///< Constructor address for EslSocketLib\r
+extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; ///< Destructor address for EslSocketLib\r
\r
-extern EFI_GUID gEfiSocketProtocolGuid;\r
-extern EFI_GUID gEfiSocketServiceBindingProtocolGuid;\r
+extern EFI_GUID gEfiSocketProtocolGuid; ///< Socket protocol GUID\r
+extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; ///< Socket layer service binding protocol GUID\r
\r
//------------------------------------------------------------------------------\r
// Socket API\r
/**\r
Accept a network connection.\r
\r
- The SocketAccept routine waits for a network connection to the socket.\r
- It is able to return the remote network address to the caller if\r
- requested.\r
+ This routine calls the network specific layer to remove the next\r
+ connection from the FIFO.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::accept calls this routine to poll for a network\r
+ connection to the socket. When a connection is available\r
+ this routine returns the ::EFI_SOCKET_PROTOCOL structure address\r
+ associated with the new socket and the remote network address\r
+ if requested.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] pSockAddr Address of a buffer to receive the remote\r
network address.\r
On output specifies the length of the\r
remote network address.\r
\r
- @param [out] ppSocketProtocol Address of a buffer to receive the socket protocol\r
- instance associated with the new socket.\r
+ @param [out] ppSocketProtocol Address of a buffer to receive the\r
+ ::EFI_SOCKET_PROTOCOL instance\r
+ associated with the new socket.\r
\r
@param [out] pErrno Address to receive the errno value upon completion.\r
\r
/**\r
Bind a name to a socket.\r
\r
- The ::SocketBind routine connects a name to a socket on the local machine. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html">POSIX</a>\r
- documentation for the bind routine is available online for reference.\r
+ This routine calls the network specific layer to save the network\r
+ address of the local connection point.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::bind routine calls this routine to connect a name\r
+ (network address and port) to a socket on the local machine.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] pSockAddr Address of a sockaddr structure that contains the\r
connection point on the local machine. An IPv4 address\r
/**\r
Determine if the socket is closed\r
\r
- Reverses the operations of the ::SocketAllocate() routine.\r
+ This routine checks the state of the socket to determine if\r
+ the network specific layer has completed the close operation.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::close routine polls this routine to determine when the\r
+ close operation is complete. The close operation needs to\r
+ reverse the operations of the ::EslSocketAllocate routine.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
@param [out] pErrno Address to receive the errno value upon completion.\r
\r
@retval EFI_SUCCESS Socket successfully closed\r
/**\r
Start the close operation on the socket\r
\r
- Start closing the socket by closing all of the ports. Upon\r
- completion, the ::pfnClosePoll() routine finishes closing the\r
- socket.\r
+ This routine calls the network specific layer to initiate the\r
+ close state machine. This routine then calls the network\r
+ specific layer to determine if the close state machine has gone\r
+ to completion. The result from this poll is returned to the\r
+ caller.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::close routine calls this routine to start the close\r
+ operation which reverses the operations of the\r
+ ::EslSocketAllocate routine. The close routine then polls\r
+ the ::EslSocketClosePoll routine to determine when the\r
+ socket is closed.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
@param [in] bCloseNow Boolean to control close behavior\r
@param [out] pErrno Address to receive the errno value upon completion.\r
\r
/**\r
Connect to a remote system via the network.\r
\r
- The ::Connect routine attempts to establish a connection to a\r
- socket on the local or remote system using the specified address.\r
- The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html">POSIX</a>\r
- documentation is available online.\r
-\r
- There are three states associated with a connection:\r
- <ul>\r
- <li>Not connected</li>\r
- <li>Connection in progress</li>\r
- <li>Connected</li>\r
- </ul>\r
- In the "Not connected" state, calls to ::connect start the connection\r
- processing and update the state to "Connection in progress". During\r
- the "Connection in progress" state, connect polls for connection completion\r
- and moves the state to "Connected" after the connection is established.\r
- Note that these states are only visible when the file descriptor is marked\r
- with O_NONBLOCK. Also, the POLL_WRITE bit is set when the connection\r
- completes and may be used by poll or select as an indicator to call\r
- connect again.\r
+ This routine calls the network specific layer to establish\r
+ the remote system address and establish the connection to\r
+ the remote system.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::connect routine calls this routine to establish a\r
+ connection with the specified remote system. This routine\r
+ is designed to be polled by the connect routine for completion\r
+ of the network connection.\r
+ \r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] pSockAddr Network address of the remote system.\r
\r
/**\r
Get the local address.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ This routine calls the network specific layer to get the network\r
+ address of the local host connection point.\r
+\r
+ The ::getsockname routine calls this routine to obtain the network\r
+ address associated with the local host connection point.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [out] pAddress Network address to receive the local system address\r
\r
/**\r
Get the peer address.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ This routine calls the network specific layer to get the remote\r
+ system connection point.\r
+\r
+ The ::getpeername routine calls this routine to obtain the network\r
+ address of the remote connection point.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [out] pAddress Network address to receive the remote system address\r
\r
/**\r
Establish the known port to listen for network connections.\r
\r
- The ::SocketAisten routine places the port into a state that enables connection\r
- attempts. Connections are placed into FIFO order in a queue to be serviced\r
- by the application. The application calls the ::SocketAccept routine to remove\r
- the next connection from the queue and get the associated socket. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">POSIX</a>\r
- documentation for the bind routine is available online for reference.\r
+ This routine calls into the network protocol layer to establish\r
+ a handler that is called upon connection completion. The handler\r
+ is responsible for inserting the connection into the FIFO.\r
+\r
+ The ::listen routine indirectly calls this routine to place the\r
+ socket into a state that enables connection attempts. Connections\r
+ are placed in a FIFO that is serviced by the application. The\r
+ application calls the ::accept (::EslSocketAccept) routine to\r
+ remove the next connection from the FIFO and get the associated\r
+ socket and address.\r
\r
@param [in] pSocketProtocol Address of the socket protocol structure.\r
\r
/**\r
Get the socket options\r
\r
- Retrieve the socket options one at a time by name. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockopt.html">POSIX</a>\r
- documentation is available online.\r
+ This routine handles the socket level options and passes the\r
+ others to the network specific layer.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::getsockopt routine calls this routine to retrieve the\r
+ socket options one at a time by name.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
@param [in] level Option protocol level\r
@param [in] OptionName Name of the option\r
@param [out] pOptionValue Buffer to receive the option value\r
/**\r
Set the socket options\r
\r
- Adjust the socket options one at a time by name. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">POSIX</a>\r
- documentation is available online.\r
+ This routine handles the socket level options and passes the\r
+ others to the network specific layer.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::setsockopt routine calls this routine to adjust the socket\r
+ options one at a time by name.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
@param [in] level Option protocol level\r
@param [in] OptionName Name of the option\r
@param [in] pOptionValue Buffer containing the option value\r
@param [in] OptionLength Length of the buffer in bytes\r
@param [out] pErrno Address to receive the errno value upon completion.\r
\r
- @retval EFI_SUCCESS - Socket data successfully received\r
+ @retval EFI_SUCCESS - Option successfully set\r
\r
**/\r
typedef\r
/**\r
Poll a socket for pending activity.\r
\r
- The SocketPoll routine checks a socket for pending activity associated\r
- with the event mask. Activity is returned in the detected event buffer.\r
+ This routine builds a detected event mask which is returned to\r
+ the caller in the buffer provided.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::poll routine calls this routine to determine if the socket\r
+ needs to be serviced as a result of connection, error, receive or\r
+ transmit activity.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] Events Events of interest for this socket\r
\r
/**\r
Receive data from a network connection.\r
\r
- The ::recv routine waits for receive data from a remote network\r
- connection. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/recv.html">POSIX</a>\r
- documentation is available online.\r
+ This routine calls the network specific routine to remove the\r
+ next portion of data from the receive queue and return it to the\r
+ caller.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::recvfrom routine calls this routine to determine if any data\r
+ is received from the remote system. Note that the other routines\r
+ ::recv and ::read are layered on top of ::recvfrom.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] Flags Message control flags\r
\r
IN int * pErrno\r
);\r
\r
-/**\r
- Send data using a network connection.\r
-\r
- The SocketTransmit routine queues the data for transmission to the\r
- remote network connection.\r
-\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
- \r
- @param [in] Flags Message control flags\r
- \r
- @param [in] BufferLength Length of the the buffer\r
- \r
- @param [in] pBuffer Address of a buffer containing the data to send\r
- \r
- @param [in] pDataLength Address to receive the number of data bytes sent\r
-\r
- @param [in] pAddress Network address of the remote system address\r
-\r
- @param [in] AddressLength Length of the remote network address structure\r
-\r
- @param [out] pErrno Address to receive the errno value upon completion.\r
-\r
- @retval EFI_SUCCESS - Socket data successfully queued for transmission\r
-\r
- **/\r
-typedef\r
-EFI_STATUS\r
-(* PFN_SEND) (\r
- IN EFI_SOCKET_PROTOCOL * pSocketProtocol,\r
- IN int Flags,\r
- IN size_t BufferLength,\r
- IN CONST UINT8 * pBuffer,\r
- OUT size_t * pDataLength,\r
- IN const struct sockaddr * pAddress,\r
- IN socklen_t AddressLength,\r
- IN int * pErrno\r
- );\r
-\r
/**\r
Shutdown the socket receive and transmit operations\r
\r
- The SocketShutdown routine stops the socket receive and transmit\r
- operations.\r
+ This routine sets a flag to stop future transmissions and calls\r
+ the network specific layer to cancel the pending receive operation.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::shutdown routine calls this routine to stop receive and transmit\r
+ operations on the socket.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
\r
@param [in] How Which operations to stop\r
\r
/**\r
Initialize an endpoint for network communication.\r
\r
- The ::Socket routine initializes the communication endpoint by providing\r
- the support for the socket library function ::socket. The\r
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html">POSIX</a>\r
- documentation for the socket routine is available online for reference.\r
+ This routine initializes the communication endpoint.\r
\r
- @param [in] pSocketProtocol Address of the socket protocol structure.\r
+ The ::socket routine calls this routine indirectly to create\r
+ the communication endpoint.\r
\r
+ @param [in] pSocketProtocol Address of the socket protocol structure.\r
@param [in] domain Select the family of protocols for the client or server\r
- application.\r
-\r
- @param [in] type Specifies how to make the network connection. The following values\r
- are supported:\r
- <ul>\r
- <li>\r
- SOCK_STREAM - Connect to TCP, provides a byte stream\r
- that is manipluated by read, recv, send and write.\r
- </li>\r
- <li>\r
- SOCK_SEQPACKET - Connect to TCP, provides sequenced packet stream\r
- that is manipulated by read, recv, send and write.\r
- </li>\r
- <li>\r
- SOCK_DGRAM - Connect to UDP, provides a datagram service that is\r
- manipulated by recvfrom and sendto.\r
- </li>\r
- </ul>\r
-\r
- @param [in] protocol Specifies the lower layer protocol to use. The following\r
- values are supported:\r
- <ul>\r
- <li>IPPROTO_TCP</li> - This value must be combined with SOCK_STREAM.</li>\r
- <li>IPPROTO_UDP</li> - This value must be combined with SOCK_DGRAM.</li>\r
- </ul>\r
-\r
+ application. See the ::socket documentation for values.\r
+ @param [in] type Specifies how to make the network connection.\r
+ See the ::socket documentation for values.\r
+ @param [in] protocol Specifies the lower layer protocol to use.\r
+ See the ::socket documentation for values.\r
@param [out] pErrno Address to receive the errno value upon completion.\r
\r
@retval EFI_SUCCESS - Socket successfully created\r
IN int * pErrno\r
);\r
\r
+/**\r
+ Send data using a network connection.\r
+\r
+ This routine calls the network specific layer to queue the data\r
+ for transmission. Eventually the buffer will reach the head of\r
+ the queue and will get transmitted over the network. For datagram\r
+ sockets there is no guarantee that the data reaches the application\r
+ running on the remote system.\r
+\r
+ The ::sendto routine calls this routine to send data to the remote\r
+ system. Note that ::send and ::write are layered on top of ::sendto.\r
+\r
+ @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.\r
+ \r
+ @param [in] Flags Message control flags\r
+ \r
+ @param [in] BufferLength Length of the the buffer\r
+ \r
+ @param [in] pBuffer Address of a buffer containing the data to send\r
+ \r
+ @param [in] pDataLength Address to receive the number of data bytes sent\r
+\r
+ @param [in] pAddress Network address of the remote system address\r
+\r
+ @param [in] AddressLength Length of the remote network address structure\r
+\r
+ @param [out] pErrno Address to receive the errno value upon completion.\r
+\r
+ @retval EFI_SUCCESS - Socket data successfully queued for transmit\r
+\r
+ **/\r
+typedef\r
+EFI_STATUS\r
+(* PFN_TRANSMIT) (\r
+ IN EFI_SOCKET_PROTOCOL * pSocketProtocol,\r
+ IN int Flags,\r
+ IN size_t BufferLength,\r
+ IN CONST UINT8 * pBuffer,\r
+ OUT size_t * pDataLength,\r
+ IN const struct sockaddr * pAddress,\r
+ IN socklen_t AddressLength,\r
+ IN int * pErrno\r
+ );\r
+\r
//------------------------------------------------------------------------------\r
// Socket Protocol\r
//------------------------------------------------------------------------------\r
PFN_GET_LOCAL pfnGetLocal; ///< Get local address\r
PFN_GET_PEER pfnGetPeer; ///< Get peer address\r
PFN_LISTEN pfnListen; ///< Enable connection attempts on known port\r
- PFN_POLL pfnPoll; ///< Poll for socket activity\r
PFN_OPTION_GET pfnOptionGet; ///< Get socket options\r
PFN_OPTION_SET pfnOptionSet; ///< Set socket options\r
+ PFN_POLL pfnPoll; ///< Poll for socket activity\r
PFN_RECEIVE pfnReceive; ///< Receive data from a socket\r
- PFN_SEND pfnSend; ///< Transmit data using the socket\r
PFN_SHUTDOWN pfnShutdown; ///< Shutdown receive and transmit operations\r
PFN_SOCKET pfnSocket; ///< Initialize the socket\r
+ PFN_TRANSMIT pfnTransmit; ///< Transmit data using the socket\r
} GCC_EFI_SOCKET_PROTOCOL;\r
\r
//------------------------------------------------------------------------------\r
//------------------------------------------------------------------------------\r
\r
/**\r
- Non blocking version of accept.\r
-\r
- See ::accept\r
+ Non blocking version of ::accept.\r
\r
@param [in] s Socket file descriptor returned from ::socket.\r
\r
of the remote network address buffer. Upon return,\r
contains the length of the remote network address.\r
\r
- @returns This routine returns zero if successful and -1 when an error occurs.\r
- In the case of an error, errno contains more details.\r
+ @return This routine returns zero if successful and -1 when an error occurs.\r
+ In the case of an error, ::errno contains more details.\r
\r
**/\r
int\r
);\r
\r
/**\r
- Connect to the socket driver\r
+ Free the socket resources\r
+\r
+ This releases the socket resources allocated by calling\r
+ EslServiceGetProtocol.\r
+\r
+ This routine is called from the ::close routine in BsdSocketLib\r
+ to release the socket resources.\r
+\r
+ @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL\r
+ structure\r
+\r
+ @return Value for ::errno, zero (0) indicates success.\r
+\r
+ **/\r
+int\r
+EslServiceFreeProtocol (\r
+ IN EFI_SOCKET_PROTOCOL * pSocketProtocol\r
+ );\r
+\r
+/**\r
+ Connect to the EFI socket library\r
\r
@param [in] ppSocketProtocol Address to receive the socket protocol address\r
\r
- @retval 0 Successfully returned the socket protocol\r
- @retval other Value for errno\r
+ @return Value for ::errno, zero (0) indicates success.\r
+\r
**/\r
int\r
EslServiceGetProtocol (\r
projects / mirror_edk2.git / blobdiff