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