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