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