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