StdLib/Include/Efi/EfiSocketLib.h

   1 /** @file
   2   Definitions for the EFI Socket layer library.
   3
   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
   9
  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.
  12
  13 **/
  14
  15 #ifndef _EFI_SOCKET_LIB_H_
  16 #define _EFI_SOCKET_LIB_H_
  17
  18 #include <Uefi.h>
  19
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/UefiLib.h>
  25
  26 #include <Protocol/EfiSocket.h>
  27 #include <Protocol/ServiceBinding.h>
  28 #include <Protocol/Tcp4.h>
  29 #include <Protocol/Tcp6.h>
  30 #include <Protocol/Udp4.h>
  31 #include <Protocol/Udp6.h>
  32
  33 #include <sys/time.h>
  34
  35 //------------------------------------------------------------------------------
  36 //  Constants
  37 //------------------------------------------------------------------------------
  38
  39 #define DEBUG_TPL           0x40000000  ///<  Display TPL change messages
  40
  41 #define TPL_SOCKETS     TPL_CALLBACK    ///<  TPL for routine synchronization
  42
  43 //------------------------------------------------------------------------------
  44 //  Macros
  45 //------------------------------------------------------------------------------
  46
  47 #if defined(_MSC_VER)           /* Handle Microsoft VC++ compiler specifics. */
  48 #define DBG_ENTER()             DEBUG (( DEBUG_INFO, "Entering " __FUNCTION__ "\n" )) ///<  Display routine entry
  49 #define DBG_EXIT()              DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ "\n" ))  ///<  Display routine exit
  50 #define DBG_EXIT_DEC(Status)    DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: %d\n", Status ))      ///<  Display routine exit with decimal value
  51 #define DBG_EXIT_HEX(Status)    DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: 0x%08x\n", Status ))  ///<  Display routine exit with hex value
  52 #define DBG_EXIT_STATUS(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: %r\n", Status ))      ///<  Display routine exit with status value
  53 #define DBG_EXIT_TF(Status)     DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", returning %s\n", (FALSE == Status) ? L"FALSE" : L"TRUE" ))  ///<  Display routine with TRUE/FALSE value
  54 #else   //  _MSC_VER
  55 #define DBG_ENTER()               ///<  Display routine entry
  56 #define DBG_EXIT()                ///<  Display routine exit
  57 #define DBG_EXIT_DEC(Status)      ///<  Display routine exit with decimal value
  58 #define DBG_EXIT_HEX(Status)      ///<  Display routine exit with hex value
  59 #define DBG_EXIT_STATUS(Status)   ///<  Display routine exit with status value
  60 #define DBG_EXIT_TF(Status)       ///<  Display routine with TRUE/FALSE value
  61 #endif  //  _MSC_VER
  62
  63 #define DIM(x)    ( sizeof ( x ) / sizeof ( x[0] ))   ///<  Compute the number of entries in an array
  64
  65 /**
  66   Verify new TPL value
  67
  68   This macro which is enabled when debug is enabled verifies that
  69   the new TPL value is >= the current TPL value.
  70 **/
  71 #ifdef VERIFY_TPL
  72 #undef VERIFY_TPL
  73 #endif  //  VERIFY_TPL
  74
  75 #if !defined(MDEPKG_NDEBUG)
  76
  77 /**
  78   Verify that the TPL is at the correct level
  79 **/
  80 #define VERIFY_AT_TPL(tpl)                           \
  81 {                                                 \
  82   EFI_TPL PreviousTpl;                            \
  83                                                   \
  84   PreviousTpl = EfiGetCurrentTpl ( );             \
  85   if ( PreviousTpl != tpl ) {                     \
  86     DEBUG (( DEBUG_ERROR | DEBUG_TPL,             \
  87               "Current TPL: %d, New TPL: %d\r\n", \
  88               PreviousTpl, tpl ));                \
  89     ASSERT ( PreviousTpl == tpl );                \
  90   }                                               \
  91 }
  92
  93 #define VERIFY_TPL(tpl)                           \
  94 {                                                 \
  95   EFI_TPL PreviousTpl;                            \
  96                                                   \
  97   PreviousTpl = EfiGetCurrentTpl ( );             \
  98   if ( PreviousTpl > tpl ) {                      \
  99     DEBUG (( DEBUG_ERROR | DEBUG_TPL,             \
 100               "Current TPL: %d, New TPL: %d\r\n", \
 101               PreviousTpl, tpl ));                \
 102     ASSERT ( PreviousTpl <= tpl );                \
 103   }                                               \
 104 }
 105
 106 #else   //  MDEPKG_NDEBUG
 107
 108 #define VERIFY_AT_TPL(tpl)    ///<  Verify that the TPL is at the correct level
 109 #define VERIFY_TPL(tpl)       ///<  Verify that the TPL is at the correct level
 110
 111 #endif  //  MDEPKG_NDEBUG
 112
 113 /**
 114   Raise TPL to the specified level
 115 **/
 116 #define RAISE_TPL(PreviousTpl, tpl)     \
 117   VERIFY_TPL ( tpl );                   \
 118   PreviousTpl = gBS->RaiseTPL ( tpl );
 119
 120 /**
 121   Restore the TPL to the previous value
 122 **/
 123 #define RESTORE_TPL(tpl)            \
 124   gBS->RestoreTPL ( tpl )
 125
 126 //------------------------------------------------------------------------------
 127 // Data Types
 128 //------------------------------------------------------------------------------
 129
 130 typedef struct _ESL_SERVICE ESL_SERVICE;  ///<  Forward delcaration
 131
 132 /**
 133   Protocol binding and installation control structure
 134
 135   The driver uses this structure to simplify the driver binding processing.
 136 **/
 137 typedef struct {
 138   CHAR16 * pName;                 ///<  Protocol name
 139   EFI_GUID * pNetworkBinding;     ///<  Network service binding protocol for socket support
 140   EFI_GUID * pNetworkProtocolGuid;///<  Network protocol GUID
 141   CONST EFI_GUID * pTagGuid;      ///<  Tag to mark protocol in use
 142   UINTN ServiceListOffset;        ///<  Offset in ::ESL_LAYER for the list of services
 143   UINTN RxIo;                     ///<  Number of receive ESL_IO_MGMT structures for data
 144   UINTN TxIoNormal;               ///<  Number of transmit ESL_IO_MGMT structures for normal data
 145   UINTN TxIoUrgent;               ///<  Number of transmit ESL_IO_MGMT structures for urgent data
 146 } ESL_SOCKET_BINDING;
 147
 148 //------------------------------------------------------------------------------
 149 // GUIDs
 150 //------------------------------------------------------------------------------
 151
 152 extern CONST EFI_GUID mEslIp4ServiceGuid;   ///<  Tag GUID for the IPv4 layer
 153 extern CONST EFI_GUID mEslIp6ServiceGuid;   ///<  Tag GUID for the IPv6 layer
 154 extern CONST EFI_GUID mEslTcp4ServiceGuid;  ///<  Tag GUID for the TCPv4 layer
 155 extern CONST EFI_GUID mEslTcp6ServiceGuid;  ///<  Tag GUID for the TCPv6 layer
 156 extern CONST EFI_GUID mEslUdp4ServiceGuid;  ///<  Tag GUID for the UDPv4 layer
 157 extern CONST EFI_GUID mEslUdp6ServiceGuid;  ///<  Tag GUID for the UDPv6 layer
 158
 159 //------------------------------------------------------------------------------
 160 // Data
 161 //------------------------------------------------------------------------------
 162
 163 extern CONST ESL_SOCKET_BINDING cEslSocketBinding[];///<  List of network service bindings
 164 extern CONST UINTN cEslSocketBindingEntries;        ///<  Number of network service bindings
 165
 166 //------------------------------------------------------------------------------
 167 // DXE Support Routines
 168 //------------------------------------------------------------------------------
 169
 170 /**
 171   Creates a child handle and installs a protocol.
 172
 173   When the socket application is linked against UseSocketDxe, the ::socket
 174   routine indirectly calls this routine in SocketDxe to create a child
 175   handle if necessary and install the socket protocol on the handle.
 176   Upon return, EslServiceGetProtocol in UseSocketLib returns the
 177   ::EFI_SOCKET_PROTOCOL address to the socket routine.
 178
 179   @param [in] pThis        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
 180   @param [in] pChildHandle Pointer to the handle of the child to create. If it is NULL,
 181                            then a new handle is created. If it is a pointer to an existing UEFI handle,
 182                            then the protocol is added to the existing UEFI handle.
 183
 184   @retval EFI_SUCCESS           The protocol was added to ChildHandle.
 185   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
 186   @retval EFI_OUT_OF_RESOURCES  There are not enough resources availabe to create
 187                                 the child
 188   @retval other                 The child handle was not created
 189
 190 **/
 191 EFI_STATUS
 192 EFIAPI
 193 EslDxeCreateChild (
 194   IN     EFI_SERVICE_BINDING_PROTOCOL * pThis,
 195   IN OUT EFI_HANDLE * pChildHandle
 196   );
 197
 198 /**
 199   Destroys a child handle with a protocol installed on it.
 200
 201   When the socket application is linked against UseSocketDxe, the ::close
 202   routine indirectly calls this routine in SocketDxe to undo the operations
 203   done by the ::EslDxeCreateChild routine.  This routine removes the socket
 204   protocol from the handle and then destroys the child handle if there are
 205   no other protocols attached.
 206
 207   @param [in] pThis       Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
 208   @param [in] ChildHandle Handle of the child to destroy
 209
 210   @retval EFI_SUCCESS           The protocol was removed from ChildHandle.
 211   @retval EFI_UNSUPPORTED       ChildHandle does not support the protocol that is being removed.
 212   @retval EFI_INVALID_PARAMETER Child handle is not a valid UEFI Handle.
 213   @retval EFI_ACCESS_DENIED     The protocol could not be removed from the ChildHandle
 214                                 because its services are being used.
 215   @retval other                 The child handle was not destroyed
 216
 217 **/
 218 EFI_STATUS
 219 EFIAPI
 220 EslDxeDestroyChild (
 221   IN EFI_SERVICE_BINDING_PROTOCOL * pThis,
 222   IN EFI_HANDLE ChildHandle
 223   );
 224
 225 /**
 226 Install the socket service
 227
 228 SocketDxe uses this routine to announce the socket interface to
 229 the rest of EFI.
 230
 231 @param [in] pImageHandle      Address of the image handle
 232
 233 @retval EFI_SUCCESS     Service installed successfully
 234 **/
 235 EFI_STATUS
 236 EFIAPI
 237 EslDxeInstall (
 238   IN EFI_HANDLE * pImageHandle
 239   );
 240
 241 /**
 242 Uninstall the socket service
 243
 244 SocketDxe uses this routine to notify EFI that the socket layer
 245 is no longer available.
 246
 247 @param [in] ImageHandle       Handle for the image.
 248
 249 @retval EFI_SUCCESS     Service installed successfully
 250 **/
 251 EFI_STATUS
 252 EFIAPI
 253 EslDxeUninstall (
 254   IN EFI_HANDLE ImageHandle
 255   );
 256
 257 //------------------------------------------------------------------------------
 258 // Service Support Routines
 259 //------------------------------------------------------------------------------
 260
 261 /**
 262   Connect to the network service bindings
 263
 264   Walk the network service protocols on the controller handle and
 265   locate any that are not in use.  Create ::ESL_SERVICE structures to
 266   manage the network layer interfaces for the socket driver.  Tag
 267   each of the network interfaces that are being used.  Finally, this
 268   routine calls ESL_SOCKET_BINDING::pfnInitialize to prepare the network
 269   interface for use by the socket layer.
 270
 271   @param [in] BindingHandle    Handle for protocol binding.
 272   @param [in] Controller       Handle of device to work with.
 273
 274   @retval EFI_SUCCESS          This driver is added to Controller.
 275   @retval other                This driver does not support this device.
 276
 277 **/
 278 EFI_STATUS
 279 EFIAPI
 280 EslServiceConnect (
 281   IN EFI_HANDLE BindingHandle,
 282   IN EFI_HANDLE Controller
 283   );
 284
 285 /**
 286   Shutdown the connections to the network layer by locating the
 287   tags on the network interfaces established by ::EslServiceConnect.
 288   This routine calls ESL_SOCKET_BINDING::pfnShutdown to shutdown the any
 289   activity on the network interface and then free the ::ESL_SERVICE
 290   structures.
 291
 292   @param [in] BindingHandle    Handle for protocol binding.
 293   @param [in] Controller       Handle of device to stop driver on.
 294
 295   @retval EFI_SUCCESS          This driver is removed Controller.
 296   @retval EFI_DEVICE_ERROR     The device could not be stopped due to a device error.
 297   @retval other                This driver was not removed from this device.
 298
 299 **/
 300 EFI_STATUS
 301 EFIAPI
 302 EslServiceDisconnect (
 303   IN  EFI_HANDLE BindingHandle,
 304   IN  EFI_HANDLE Controller
 305   );
 306
 307 /**
 308 Initialize the service layer
 309
 310 @param [in] ImageHandle       Handle for the image.
 311
 312 **/
 313 VOID
 314 EFIAPI
 315 EslServiceLoad (
 316   IN EFI_HANDLE ImageHandle
 317   );
 318
 319 /**
 320   Shutdown the service layer
 321
 322 **/
 323 VOID
 324 EFIAPI
 325 EslServiceUnload (
 326   VOID
 327   );
 328
 329 //------------------------------------------------------------------------------
 330 // Socket Protocol Routines
 331 //------------------------------------------------------------------------------
 332
 333 /**
 334   Bind a name to a socket.
 335
 336   This routine calls the network specific layer to save the network
 337   address of the local connection point.
 338
 339   The ::bind routine calls this routine to connect a name
 340   (network address and port) to a socket on the local machine.
 341
 342   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 343
 344   @param [in] pSockAddr Address of a sockaddr structure that contains the
 345                         connection point on the local machine.  An IPv4 address
 346                         of INADDR_ANY specifies that the connection is made to
 347                         all of the network stacks on the platform.  Specifying a
 348                         specific IPv4 address restricts the connection to the
 349                         network stack supporting that address.  Specifying zero
 350                         for the port causes the network layer to assign a port
 351                         number from the dynamic range.  Specifying a specific
 352                         port number causes the network layer to use that port.
 353
 354   @param [in] SockAddrLength  Specifies the length in bytes of the sockaddr structure.
 355
 356   @param [out] pErrno   Address to receive the errno value upon completion.
 357
 358   @retval EFI_SUCCESS - Socket successfully created
 359
 360  **/
 361 EFI_STATUS
 362 EslSocketBind (
 363   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 364   IN CONST struct sockaddr * pSockAddr,
 365   IN socklen_t SockAddrLength,
 366   OUT int * pErrno
 367   );
 368
 369 /**
 370   Determine if the socket is closed
 371
 372   This routine checks the state of the socket to determine if
 373   the network specific layer has completed the close operation.
 374
 375   The ::close routine polls this routine to determine when the
 376   close operation is complete.  The close operation needs to
 377   reverse the operations of the ::EslSocketAllocate routine.
 378
 379   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 380   @param [out] pErrno         Address to receive the errno value upon completion.
 381
 382   @retval EFI_SUCCESS     Socket successfully closed
 383   @retval EFI_NOT_READY   Close still in progress
 384   @retval EFI_ALREADY     Close operation already in progress
 385   @retval Other           Failed to close the socket
 386
 387 **/
 388 EFI_STATUS
 389 EslSocketClosePoll (
 390   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 391   IN int * pErrno
 392   );
 393
 394 /**
 395   Start the close operation on the socket
 396
 397   This routine calls the network specific layer to initiate the
 398   close state machine.  This routine then calls the network
 399   specific layer to determine if the close state machine has gone
 400   to completion.  The result from this poll is returned to the
 401   caller.
 402
 403   The ::close routine calls this routine to start the close
 404   operation which reverses the operations of the
 405   ::EslSocketAllocate routine.  The close routine then polls
 406   the ::EslSocketClosePoll routine to determine when the
 407   socket is closed.
 408
 409   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 410   @param [in] bCloseNow       Boolean to control close behavior
 411   @param [out] pErrno         Address to receive the errno value upon completion.
 412
 413   @retval EFI_SUCCESS     Socket successfully closed
 414   @retval EFI_NOT_READY   Close still in progress
 415   @retval EFI_ALREADY     Close operation already in progress
 416   @retval Other           Failed to close the socket
 417
 418 **/
 419 EFI_STATUS
 420 EslSocketCloseStart (
 421   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 422   IN BOOLEAN bCloseNow,
 423   IN int * pErrno
 424   );
 425
 426 /**
 427   Connect to a remote system via the network.
 428
 429   This routine calls the network specific layer to establish
 430   the remote system address and establish the connection to
 431   the remote system.
 432
 433   The ::connect routine calls this routine to establish a
 434   connection with the specified remote system.  This routine
 435   is designed to be polled by the connect routine for completion
 436   of the network connection.
 437
 438   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 439
 440   @param [in] pSockAddr       Network address of the remote system.
 441
 442   @param [in] SockAddrLength  Length in bytes of the network address.
 443
 444   @param [out] pErrno   Address to receive the errno value upon completion.
 445
 446   @retval EFI_SUCCESS   The connection was successfully established.
 447   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 448   @retval Others        The connection attempt failed.
 449
 450  **/
 451 EFI_STATUS
 452 EslSocketConnect (
 453   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 454   IN const struct sockaddr * pSockAddr,
 455   IN socklen_t SockAddrLength,
 456   IN int * pErrno
 457   );
 458
 459 /**
 460   Get the local address.
 461
 462   This routine calls the network specific layer to get the network
 463   address of the local host connection point.
 464
 465   The ::getsockname routine calls this routine to obtain the network
 466   address associated with the local host connection point.
 467
 468   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 469
 470   @param [out] pAddress       Network address to receive the local system address
 471
 472   @param [in,out] pAddressLength  Length of the local network address structure
 473
 474   @param [out] pErrno         Address to receive the errno value upon completion.
 475
 476   @retval EFI_SUCCESS - Local address successfully returned
 477
 478  **/
 479 EFI_STATUS
 480 EslSocketGetLocalAddress (
 481   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 482   OUT struct sockaddr * pAddress,
 483   IN OUT socklen_t * pAddressLength,
 484   IN int * pErrno
 485   );
 486
 487 /**
 488   Get the peer address.
 489
 490   This routine calls the network specific layer to get the remote
 491   system connection point.
 492
 493   The ::getpeername routine calls this routine to obtain the network
 494   address of the remote connection point.
 495
 496   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 497
 498   @param [out] pAddress       Network address to receive the remote system address
 499
 500   @param [in,out] pAddressLength  Length of the remote network address structure
 501
 502   @param [out] pErrno         Address to receive the errno value upon completion.
 503
 504   @retval EFI_SUCCESS - Remote address successfully returned
 505
 506  **/
 507 EFI_STATUS
 508 EslSocketGetPeerAddress (
 509   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 510   OUT struct sockaddr * pAddress,
 511   IN OUT socklen_t * pAddressLength,
 512   IN int * pErrno
 513   );
 514
 515 /**
 516   Establish the known port to listen for network connections.
 517
 518   This routine calls into the network protocol layer to establish
 519   a handler that is called upon connection completion.  The handler
 520   is responsible for inserting the connection into the FIFO.
 521
 522   The ::listen routine indirectly calls this routine to place the
 523   socket into a state that enables connection attempts.  Connections
 524   are placed in a FIFO that is serviced by the application.  The
 525   application calls the ::accept (::EslSocketAccept) routine to
 526   remove the next connection from the FIFO and get the associated
 527   socket and address.
 528
 529   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 530
 531   @param [in] Backlog         Backlog specifies the maximum FIFO depth for
 532                               the connections waiting for the application
 533                               to call accept.  Connection attempts received
 534                               while the queue is full are refused.
 535
 536   @param [out] pErrno         Address to receive the errno value upon completion.
 537
 538   @retval EFI_SUCCESS - Socket successfully created
 539   @retval Other - Failed to enable the socket for listen
 540
 541 **/
 542 EFI_STATUS
 543 EslSocketListen (
 544   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 545   IN INT32 Backlog,
 546   OUT int * pErrno
 547   );
 548
 549 /**
 550   Get the socket options
 551
 552   This routine handles the socket level options and passes the
 553   others to the network specific layer.
 554
 555   The ::getsockopt routine calls this routine to retrieve the
 556   socket options one at a time by name.
 557
 558   @param [in] pSocketProtocol   Address of an ::EFI_SOCKET_PROTOCOL structure.
 559   @param [in] level             Option protocol level
 560   @param [in] OptionName        Name of the option
 561   @param [out] pOptionValue     Buffer to receive the option value
 562   @param [in,out] pOptionLength Length of the buffer in bytes,
 563                                 upon return length of the option value in bytes
 564   @param [out] pErrno           Address to receive the errno value upon completion.
 565
 566   @retval EFI_SUCCESS - Socket data successfully received
 567
 568  **/
 569 EFI_STATUS
 570 EslSocketOptionGet (
 571   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 572   IN int level,
 573   IN int option_name,
 574   OUT void * __restrict option_value,
 575   IN OUT socklen_t * __restrict option_len,
 576   IN int * pErrno
 577   );
 578
 579 /**
 580   Set the socket options
 581
 582   This routine handles the socket level options and passes the
 583   others to the network specific layer.
 584
 585   The ::setsockopt routine calls this routine to adjust the socket
 586   options one at a time by name.
 587
 588   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 589   @param [in] level           Option protocol level
 590   @param [in] OptionName      Name of the option
 591   @param [in] pOptionValue    Buffer containing the option value
 592   @param [in] OptionLength    Length of the buffer in bytes
 593   @param [out] pErrno         Address to receive the errno value upon completion.
 594
 595   @retval EFI_SUCCESS - Option successfully set
 596
 597  **/
 598 EFI_STATUS
 599 EslSocketOptionSet (
 600   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 601   IN int level,
 602   IN int option_name,
 603   IN CONST void * option_value,
 604   IN socklen_t option_len,
 605   IN int * pErrno
 606   );
 607
 608 /**
 609   Poll a socket for pending activity.
 610
 611   This routine builds a detected event mask which is returned to
 612   the caller in the buffer provided.
 613
 614   The ::poll routine calls this routine to determine if the socket
 615   needs to be serviced as a result of connection, error, receive or
 616   transmit activity.
 617
 618   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 619
 620   @param [in] Events    Events of interest for this socket
 621
 622   @param [in] pEvents   Address to receive the detected events
 623
 624   @param [out] pErrno   Address to receive the errno value upon completion.
 625
 626   @retval EFI_SUCCESS - Socket successfully polled
 627   @retval EFI_INVALID_PARAMETER - When pEvents is NULL
 628
 629  **/
 630 EFI_STATUS
 631 EslSocketPoll (
 632   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 633   IN short Events,
 634   IN short * pEvents,
 635   IN int * pErrno
 636   );
 637
 638 /**
 639   Receive data from a network connection.
 640
 641   This routine calls the network specific routine to remove the
 642   next portion of data from the receive queue and return it to the
 643   caller.
 644
 645   The ::recvfrom routine calls this routine to determine if any data
 646   is received from the remote system.  Note that the other routines
 647   ::recv and ::read are layered on top of ::recvfrom.
 648
 649   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 650
 651   @param [in] Flags           Message control flags
 652
 653   @param [in] BufferLength    Length of the the buffer
 654
 655   @param [in] pBuffer         Address of a buffer to receive the data.
 656
 657   @param [in] pDataLength     Number of received data bytes in the buffer.
 658
 659   @param [out] pAddress       Network address to receive the remote system address
 660
 661   @param [in,out] pAddressLength  Length of the remote network address structure
 662
 663   @param [out] pErrno         Address to receive the errno value upon completion.
 664
 665   @retval EFI_SUCCESS - Socket data successfully received
 666
 667  **/
 668 EFI_STATUS
 669 EslSocketReceive (
 670   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 671   IN INT32 Flags,
 672   IN size_t BufferLength,
 673   IN UINT8 * pBuffer,
 674   OUT size_t * pDataLength,
 675   OUT struct sockaddr * pAddress,
 676   IN OUT socklen_t * pAddressLength,
 677   IN int * pErrno
 678   );
 679
 680 /**
 681   Shutdown the socket receive and transmit operations
 682
 683   This routine sets a flag to stop future transmissions and calls
 684   the network specific layer to cancel the pending receive operation.
 685
 686   The ::shutdown routine calls this routine to stop receive and transmit
 687   operations on the socket.
 688
 689   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 690
 691   @param [in] How             Which operations to stop
 692
 693   @param [out] pErrno         Address to receive the errno value upon completion.
 694
 695   @retval EFI_SUCCESS - Socket operations successfully shutdown
 696
 697  **/
 698 EFI_STATUS
 699 EslSocketShutdown (
 700   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 701   IN int How,
 702   IN int * pErrno
 703   );
 704
 705 /**
 706   Send data using a network connection.
 707
 708   This routine calls the network specific layer to queue the data
 709   for transmission.  Eventually the buffer will reach the head of
 710   the queue and will get transmitted over the network.  For datagram
 711   sockets there is no guarantee that the data reaches the application
 712   running on the remote system.
 713
 714   The ::sendto routine calls this routine to send data to the remote
 715   system.  Note that ::send and ::write are layered on top of ::sendto.
 716
 717   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
 718
 719   @param [in] Flags           Message control flags
 720
 721   @param [in] BufferLength    Length of the the buffer
 722
 723   @param [in] pBuffer         Address of a buffer containing the data to send
 724
 725   @param [in] pDataLength     Address to receive the number of data bytes sent
 726
 727   @param [in] pAddress        Network address of the remote system address
 728
 729   @param [in] AddressLength   Length of the remote network address structure
 730
 731   @param [out] pErrno         Address to receive the errno value upon completion.
 732
 733   @retval EFI_SUCCESS - Socket data successfully queued for transmit
 734
 735  **/
 736 EFI_STATUS
 737 EslSocketTransmit (
 738   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 739   IN int Flags,
 740   IN size_t BufferLength,
 741   IN CONST UINT8 * pBuffer,
 742   OUT size_t * pDataLength,
 743   IN const struct sockaddr * pAddress,
 744   IN socklen_t AddressLength,
 745   IN int * pErrno
 746   );
 747
 748 //------------------------------------------------------------------------------
 749
 750 #endif  //  _EFI_SOCKET_LIB_H_