StdLib/Include/Protocol/EfiSocket.h

   1 /** @file
   2   Definitions for the EFI Socket protocol.
   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.php
   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_H_
  16 #define _EFI_SOCKET_H_
  17
  18 #include <errno.h>
  19 #include <Uefi.h>
  20
  21 #include <netinet/in.h>
  22
  23 #include <sys/poll.h>
  24 #include <sys/socket.h>
  25
  26 //------------------------------------------------------------------------------
  27 //  Data Types
  28 //------------------------------------------------------------------------------
  29
  30 /**
  31 EfiSocketLib (SocketDxe) interface
  32 **/
  33 typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL;
  34
  35 /**
  36   Constructor/Destructor
  37
  38   @retval EFI_SUCCESS       The operation was successful
  39
  40  **/
  41 typedef
  42 EFI_STATUS
  43 (* PFN_ESL_xSTRUCTOR) (
  44   VOID
  45   );
  46
  47 //------------------------------------------------------------------------------
  48 // Data
  49 //------------------------------------------------------------------------------
  50
  51 extern PFN_ESL_xSTRUCTOR mpfnEslConstructor;  ///<  Constructor address for EslSocketLib
  52 extern PFN_ESL_xSTRUCTOR mpfnEslDestructor;   ///<  Destructor address for EslSocketLib
  53
  54 extern EFI_GUID  gEfiSocketProtocolGuid;      ///<  Socket protocol GUID
  55 extern EFI_GUID  gEfiSocketServiceBindingProtocolGuid;  ///<  Socket layer service binding protocol GUID
  56
  57 //------------------------------------------------------------------------------
  58 //  Socket API
  59 //------------------------------------------------------------------------------
  60
  61 /**
  62   Accept a network connection.
  63
  64   This routine calls the network specific layer to remove the next
  65   connection from the FIFO.
  66
  67   The ::accept calls this routine to poll for a network
  68   connection to the socket.  When a connection is available
  69   this routine returns the ::EFI_SOCKET_PROTOCOL structure address
  70   associated with the new socket and the remote network address
  71   if requested.
  72
  73   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
  74
  75   @param [in] pSockAddr       Address of a buffer to receive the remote
  76                               network address.
  77
  78   @param [in, out] pSockAddrLength  Length in bytes of the address buffer.
  79                                     On output specifies the length of the
  80                                     remote network address.
  81
  82   @param [out] ppSocketProtocol Address of a buffer to receive the
  83                                 ::EFI_SOCKET_PROTOCOL instance
  84                                 associated with the new socket.
  85
  86   @param [out] pErrno   Address to receive the errno value upon completion.
  87
  88   @retval EFI_SUCCESS   New connection successfully created
  89   @retval EFI_NOT_READY No connection is available
  90
  91  **/
  92 typedef
  93 EFI_STATUS
  94 (* PFN_ACCEPT) (
  95   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
  96   IN struct sockaddr * pSockAddr,
  97   IN OUT socklen_t * pSockAddrLength,
  98   IN EFI_SOCKET_PROTOCOL ** ppSocketProtocol,
  99   IN int * pErrno
 100   );
 101
 102 /**
 103   Bind a name to a socket.
 104
 105   This routine calls the network specific layer to save the network
 106   address of the local connection point.
 107
 108   The ::bind routine calls this routine to connect a name
 109   (network address and port) to a socket on the local machine.
 110
 111   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 112
 113   @param [in] pSockAddr Address of a sockaddr structure that contains the
 114                         connection point on the local machine.  An IPv4 address
 115                         of INADDR_ANY specifies that the connection is made to
 116                         all of the network stacks on the platform.  Specifying a
 117                         specific IPv4 address restricts the connection to the
 118                         network stack supporting that address.  Specifying zero
 119                         for the port causes the network layer to assign a port
 120                         number from the dynamic range.  Specifying a specific
 121                         port number causes the network layer to use that port.
 122
 123   @param [in] SockAddrLen   Specifies the length in bytes of the sockaddr structure.
 124
 125   @param [out] pErrno   Address to receive the errno value upon completion.
 126
 127   @retval EFI_SUCCESS - Socket successfully created
 128
 129  **/
 130 typedef
 131 EFI_STATUS
 132 (* PFN_BIND) (
 133   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 134   IN const struct sockaddr * pSockAddr,
 135   IN socklen_t SockAddrLength,
 136   OUT int * pErrno
 137   );
 138
 139 /**
 140   Determine if the socket is closed
 141
 142   This routine checks the state of the socket to determine if
 143   the network specific layer has completed the close operation.
 144
 145   The ::close routine polls this routine to determine when the
 146   close operation is complete.  The close operation needs to
 147   reverse the operations of the ::EslSocketAllocate routine.
 148
 149   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 150   @param [out] pErrno         Address to receive the errno value upon completion.
 151
 152   @retval EFI_SUCCESS     Socket successfully closed
 153   @retval EFI_NOT_READY   Close still in progress
 154   @retval EFI_ALREADY     Close operation already in progress
 155   @retval Other           Failed to close the socket
 156
 157 **/
 158 typedef
 159 EFI_STATUS
 160 (* PFN_CLOSE_POLL) (
 161   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 162   IN int * pErrno
 163   );
 164
 165 /**
 166   Start the close operation on the socket
 167
 168   This routine calls the network specific layer to initiate the
 169   close state machine.  This routine then calls the network
 170   specific layer to determine if the close state machine has gone
 171   to completion.  The result from this poll is returned to the
 172   caller.
 173
 174   The ::close routine calls this routine to start the close
 175   operation which reverses the operations of the
 176   ::EslSocketAllocate routine.  The close routine then polls
 177   the ::EslSocketClosePoll routine to determine when the
 178   socket is closed.
 179
 180   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 181   @param [in] bCloseNow       Boolean to control close behavior
 182   @param [out] pErrno         Address to receive the errno value upon completion.
 183
 184   @retval EFI_SUCCESS     Socket successfully closed
 185   @retval EFI_NOT_READY   Close still in progress
 186   @retval EFI_ALREADY     Close operation already in progress
 187   @retval Other           Failed to close the socket
 188
 189 **/
 190 typedef
 191 EFI_STATUS
 192 (* PFN_CLOSE_START) (
 193   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 194   IN BOOLEAN bCloseNow,
 195   IN int * pErrno
 196   );
 197
 198 /**
 199   Connect to a remote system via the network.
 200
 201   This routine calls the network specific layer to establish
 202   the remote system address and establish the connection to
 203   the remote system.
 204
 205   The ::connect routine calls this routine to establish a
 206   connection with the specified remote system.  This routine
 207   is designed to be polled by the connect routine for completion
 208   of the network connection.
 209
 210   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 211
 212   @param [in] pSockAddr       Network address of the remote system.
 213
 214   @param [in] SockAddrLength  Length in bytes of the network address.
 215
 216   @param [out] pErrno   Address to receive the errno value upon completion.
 217
 218   @retval EFI_SUCCESS   The connection was successfully established.
 219   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 220   @retval Others        The connection attempt failed.
 221
 222  **/
 223 typedef
 224 EFI_STATUS
 225 (* PFN_CONNECT) (
 226   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 227   IN const struct sockaddr * pSockAddr,
 228   IN socklen_t SockAddrLength,
 229   IN int * pErrno
 230   );
 231
 232 /**
 233   Get the local address.
 234
 235   This routine calls the network specific layer to get the network
 236   address of the local host connection point.
 237
 238   The ::getsockname routine calls this routine to obtain the network
 239   address associated with the local host connection point.
 240
 241   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 242
 243   @param [out] pAddress       Network address to receive the local system address
 244
 245   @param [in,out] pAddressLength  Length of the local network address structure
 246
 247   @param [out] pErrno         Address to receive the errno value upon completion.
 248
 249   @retval EFI_SUCCESS - Local address successfully returned
 250
 251  **/
 252 typedef
 253 EFI_STATUS
 254 (* PFN_GET_LOCAL) (
 255   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 256   OUT struct sockaddr * pAddress,
 257   IN OUT socklen_t * pAddressLength,
 258   IN int * pErrno
 259   );
 260
 261 /**
 262   Get the peer address.
 263
 264   This routine calls the network specific layer to get the remote
 265   system connection point.
 266
 267   The ::getpeername routine calls this routine to obtain the network
 268   address of the remote connection point.
 269
 270   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 271
 272   @param [out] pAddress       Network address to receive the remote system address
 273
 274   @param [in,out] pAddressLength  Length of the remote network address structure
 275
 276   @param [out] pErrno         Address to receive the errno value upon completion.
 277
 278   @retval EFI_SUCCESS - Remote address successfully returned
 279
 280  **/
 281 typedef
 282 EFI_STATUS
 283 (* PFN_GET_PEER) (
 284   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 285   OUT struct sockaddr * pAddress,
 286   IN OUT socklen_t * pAddressLength,
 287   IN int * pErrno
 288   );
 289
 290 /**
 291   Establish the known port to listen for network connections.
 292
 293   This routine calls into the network protocol layer to establish
 294   a handler that is called upon connection completion.  The handler
 295   is responsible for inserting the connection into the FIFO.
 296
 297   The ::listen routine indirectly calls this routine to place the
 298   socket into a state that enables connection attempts.  Connections
 299   are placed in a FIFO that is serviced by the application.  The
 300   application calls the ::accept (::EslSocketAccept) routine to
 301   remove the next connection from the FIFO and get the associated
 302   socket and address.
 303
 304   @param [in] pSocketProtocol Address of the socket protocol structure.
 305
 306   @param [in] Backlog         Backlog specifies the maximum FIFO depth for
 307                               the connections waiting for the application
 308                               to call accept.  Connection attempts received
 309                               while the queue is full are refused.
 310
 311   @param [out] pErrno         Address to receive the errno value upon completion.
 312
 313   @retval EFI_SUCCESS - Socket successfully created
 314   @retval Other - Failed to enable the socket for listen
 315
 316 **/
 317 typedef
 318 EFI_STATUS
 319 (* PFN_LISTEN) (
 320   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 321   IN INT32 Backlog,
 322   OUT int * pErrno
 323   );
 324
 325 /**
 326   Get the socket options
 327
 328   This routine handles the socket level options and passes the
 329   others to the network specific layer.
 330
 331   The ::getsockopt routine calls this routine to retrieve the
 332   socket options one at a time by name.
 333
 334   @param [in] pSocketProtocol   Address of the ::EFI_SOCKET_PROTOCOL structure.
 335   @param [in] level             Option protocol level
 336   @param [in] OptionName        Name of the option
 337   @param [out] pOptionValue     Buffer to receive the option value
 338   @param [in,out] pOptionLength Length of the buffer in bytes,
 339                                 upon return length of the option value in bytes
 340   @param [out] pErrno           Address to receive the errno value upon completion.
 341
 342   @retval EFI_SUCCESS - Socket data successfully received
 343
 344  **/
 345 typedef
 346 EFI_STATUS
 347 (* PFN_OPTION_GET) (
 348   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 349   IN int level,
 350   IN int OptionName,
 351   OUT void * __restrict pOptionValue,
 352   IN OUT socklen_t * __restrict pOptionLength,
 353   IN int * pErrno
 354   );
 355
 356 /**
 357   Set the socket options
 358
 359   This routine handles the socket level options and passes the
 360   others to the network specific layer.
 361
 362   The ::setsockopt routine calls this routine to adjust the socket
 363   options one at a time by name.
 364
 365   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 366   @param [in] level           Option protocol level
 367   @param [in] OptionName      Name of the option
 368   @param [in] pOptionValue    Buffer containing the option value
 369   @param [in] OptionLength    Length of the buffer in bytes
 370   @param [out] pErrno         Address to receive the errno value upon completion.
 371
 372   @retval EFI_SUCCESS - Option successfully set
 373
 374  **/
 375 typedef
 376 EFI_STATUS
 377 (* PFN_OPTION_SET) (
 378   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 379   IN int level,
 380   IN int OptionName,
 381   IN CONST void * pOptionValue,
 382   IN socklen_t OptionLength,
 383   IN int * pErrno
 384   );
 385
 386 /**
 387   Poll a socket for pending activity.
 388
 389   This routine builds a detected event mask which is returned to
 390   the caller in the buffer provided.
 391
 392   The ::poll routine calls this routine to determine if the socket
 393   needs to be serviced as a result of connection, error, receive or
 394   transmit activity.
 395
 396   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 397
 398   @param [in] Events    Events of interest for this socket
 399
 400   @param [in] pEvents   Address to receive the detected events
 401
 402   @param [out] pErrno   Address to receive the errno value upon completion.
 403
 404   @retval EFI_SUCCESS - Socket successfully polled
 405   @retval EFI_INVALID_PARAMETER - When pEvents is NULL
 406
 407  **/
 408 typedef
 409 EFI_STATUS
 410 (* PFN_POLL) (
 411   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 412   IN short Events,
 413   IN short * pEvents,
 414   IN int * pErrno
 415   );
 416
 417 /**
 418   Receive data from a network connection.
 419
 420   This routine calls the network specific routine to remove the
 421   next portion of data from the receive queue and return it to the
 422   caller.
 423
 424   The ::recvfrom routine calls this routine to determine if any data
 425   is received from the remote system.  Note that the other routines
 426   ::recv and ::read are layered on top of ::recvfrom.
 427
 428   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 429
 430   @param [in] Flags           Message control flags
 431
 432   @param [in] BufferLength    Length of the the buffer
 433
 434   @param [in] pBuffer         Address of a buffer to receive the data.
 435
 436   @param [in] pDataLength     Number of received data bytes in the buffer.
 437
 438   @param [out] pAddress       Network address to receive the remote system address
 439
 440   @param [in,out] pAddressLength  Length of the remote network address structure
 441
 442   @param [out] pErrno         Address to receive the errno value upon completion.
 443
 444   @retval EFI_SUCCESS - Socket data successfully received
 445
 446  **/
 447 typedef
 448 EFI_STATUS
 449 (* PFN_RECEIVE) (
 450   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 451   IN int Flags,
 452   IN size_t BufferLength,
 453   IN UINT8 * pBuffer,
 454   OUT size_t * pDataLength,
 455   OUT struct sockaddr * pAddress,
 456   IN OUT socklen_t * pAddressLength,
 457   IN int * pErrno
 458   );
 459
 460 /**
 461   Shutdown the socket receive and transmit operations
 462
 463   This routine sets a flag to stop future transmissions and calls
 464   the network specific layer to cancel the pending receive operation.
 465
 466   The ::shutdown routine calls this routine to stop receive and transmit
 467   operations on the socket.
 468
 469   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 470
 471   @param [in] How             Which operations to stop
 472
 473   @param [out] pErrno         Address to receive the errno value upon completion.
 474
 475   @retval EFI_SUCCESS - Socket operations successfully shutdown
 476
 477  **/
 478 typedef
 479 EFI_STATUS
 480 (* PFN_SHUTDOWN) (
 481   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 482   IN int How,
 483   IN int * pErrno
 484   );
 485
 486 /**
 487   Initialize an endpoint for network communication.
 488
 489   This routine initializes the communication endpoint.
 490
 491   The ::socket routine calls this routine indirectly to create
 492   the communication endpoint.
 493
 494   @param [in] pSocketProtocol Address of the socket protocol structure.
 495   @param [in] domain    Select the family of protocols for the client or server
 496                         application.  See the ::socket documentation for values.
 497   @param [in] type      Specifies how to make the network connection.
 498                         See the ::socket documentation for values.
 499   @param [in] protocol  Specifies the lower layer protocol to use.
 500                         See the ::socket documentation for values.
 501   @param [out] pErrno   Address to receive the errno value upon completion.
 502
 503   @retval EFI_SUCCESS - Socket successfully created
 504   @retval EFI_INVALID_PARAMETER - Invalid domain value, errno = EAFNOSUPPORT
 505   @retval EFI_INVALID_PARAMETER - Invalid type value, errno = EINVAL
 506   @retval EFI_INVALID_PARAMETER - Invalid protocol value, errno = EINVAL
 507
 508  **/
 509 typedef
 510 EFI_STATUS
 511 (*PFN_SOCKET) (
 512   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 513   IN int domain,
 514   IN int type,
 515   IN int protocol,
 516   IN int * pErrno
 517   );
 518
 519 /**
 520   Send data using a network connection.
 521
 522   This routine calls the network specific layer to queue the data
 523   for transmission.  Eventually the buffer will reach the head of
 524   the queue and will get transmitted over the network.  For datagram
 525   sockets there is no guarantee that the data reaches the application
 526   running on the remote system.
 527
 528   The ::sendto routine calls this routine to send data to the remote
 529   system.  Note that ::send and ::write are layered on top of ::sendto.
 530
 531   @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.
 532
 533   @param [in] Flags           Message control flags
 534
 535   @param [in] BufferLength    Length of the the buffer
 536
 537   @param [in] pBuffer         Address of a buffer containing the data to send
 538
 539   @param [in] pDataLength     Address to receive the number of data bytes sent
 540
 541   @param [in] pAddress        Network address of the remote system address
 542
 543   @param [in] AddressLength   Length of the remote network address structure
 544
 545   @param [out] pErrno         Address to receive the errno value upon completion.
 546
 547   @retval EFI_SUCCESS - Socket data successfully queued for transmit
 548
 549  **/
 550 typedef
 551 EFI_STATUS
 552 (* PFN_TRANSMIT) (
 553   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
 554   IN int Flags,
 555   IN size_t BufferLength,
 556   IN CONST UINT8 * pBuffer,
 557   OUT size_t * pDataLength,
 558   IN const struct sockaddr * pAddress,
 559   IN socklen_t AddressLength,
 560   IN int * pErrno
 561   );
 562
 563 //------------------------------------------------------------------------------
 564 //  Socket Protocol
 565 //------------------------------------------------------------------------------
 566
 567 /**
 568   Socket protocol declaration
 569 **/
 570 typedef struct _EFI_SOCKET_PROTOCOL {
 571   EFI_HANDLE SocketHandle;        ///<  Handle for the socket
 572   PFN_ACCEPT pfnAccept;           ///<  Accept a network connection
 573   PFN_BIND pfnBind;               ///<  Bind a local address to the socket
 574   PFN_CLOSE_POLL pfnClosePoll;    ///<  Determine if the socket is closed
 575   PFN_CLOSE_START pfnCloseStart;  ///<  Start the close operation
 576   PFN_CONNECT pfnConnect;         ///<  Connect to a remote system
 577   PFN_GET_LOCAL pfnGetLocal;      ///<  Get local address
 578   PFN_GET_PEER pfnGetPeer;        ///<  Get peer address
 579   PFN_LISTEN pfnListen;           ///<  Enable connection attempts on known port
 580   PFN_OPTION_GET pfnOptionGet;    ///<  Get socket options
 581   PFN_OPTION_SET pfnOptionSet;    ///<  Set socket options
 582   PFN_POLL pfnPoll;               ///<  Poll for socket activity
 583   PFN_RECEIVE pfnReceive;         ///<  Receive data from a socket
 584   PFN_SHUTDOWN pfnShutdown;       ///<  Shutdown receive and transmit operations
 585   PFN_SOCKET pfnSocket;           ///<  Initialize the socket
 586   PFN_TRANSMIT pfnTransmit;       ///<  Transmit data using the socket
 587 } GCC_EFI_SOCKET_PROTOCOL;
 588
 589 //------------------------------------------------------------------------------
 590 //  Non-blocking routines
 591 //------------------------------------------------------------------------------
 592
 593 /**
 594   Non blocking version of ::accept.
 595
 596   @param [in] s         Socket file descriptor returned from ::socket.
 597
 598   @param [in] address   Address of a buffer to receive the remote network address.
 599
 600   @param [in, out] address_len  Address of a buffer containing the Length in bytes
 601                                 of the remote network address buffer.  Upon return,
 602                                 contains the length of the remote network address.
 603
 604   @return     This routine returns zero if successful and -1 when an error occurs.
 605               In the case of an error, ::errno contains more details.
 606
 607  **/
 608 int
 609 AcceptNB (
 610   int s,
 611   struct sockaddr * address,
 612   socklen_t * address_len
 613   );
 614
 615 /**
 616   Connect to the EFI socket library
 617
 618   @param [in] ppSocketProtocol  Address to receive the socket protocol address
 619
 620   @return       Value for ::errno, zero (0) indicates success.
 621
 622  **/
 623 int
 624 EslServiceGetProtocol (
 625   IN EFI_SOCKET_PROTOCOL ** ppSocketProtocol
 626   );
 627
 628 //------------------------------------------------------------------------------
 629
 630 #endif  //  _EFI_SOCKET_H_