text: /****************************************************************************
   *
   * Copyright 2016 Samsung Electronics All Rights Reserved.
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing,
   * software distributed under the License is distributed on an
   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
   * either express or implied. See the License for the specific
   * language governing permissions and limitations under the License.
   *
   ****************************************************************************/
  /****************************************************************************
   * include/sys/socket.h
   *
   *   Copyright (C) 2007, 2009, 2011 Gregory Nutt. All rights reserved.
   *   Author: Gregory Nutt <gnutt@nuttx.org>
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   * 3. Neither the name NuttX nor the names of its contributors may be
   *    used to endorse or promote products derived from this software
   *    without specific prior written permission.
   *
   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
   * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
   * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   * POSSIBILITY OF SUCH DAMAGE.
   *
   ****************************************************************************/
  /**
   * @defgroup NETWORK NETWORK
   * @defgroup SOCKET Socket
   * @brief Provides APIs for BSD Socket
   * @ingroup NETWORK
   *
   * @{
   */
  
  /// @file socket.h
  /// @brief Socket APIs
  #ifndef __INCLUDE_SYS_SOCKET_H
  #define __INCLUDE_SYS_SOCKET_H
  
  /****************************************************************************
   * Included Files
   ****************************************************************************/
  
  #include <tinyara/config.h>
  #include <sys/sock_internal.h>
  #include <sys/types.h>
  
  #ifdef CONFIG_NET_SOCKET
  #include <net/lwip/sockets.h>
  #include <net/lwip/api.h>
  #endif	/* CONFIG_NET_SOCKET */
  
  /****************************************************************************
   * Public Function Prototypes
   ****************************************************************************/
  
  #undef EXTERN
  #if defined(__cplusplus)
  #define EXTERN extern "C"
  extern "C" {
  #else
  #define EXTERN extern
  #endif
  
  /**
  * @brief creates an unbound socket in a communications domain.
  *
  * @param[in] domain the communications domain in which a socket is to be created.
  * @param[in] type  the type of socket to be created
  * @param[in] protocol the protocol to be used with the socket
  * @return On success, a non negative integer is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int socket(int domain, int type, int protocol);
  
  /**
  * @brief  assigns an address to an unnamed socket.
  *
  * @param[in] sockfd the file descriptor of the socket to be bound.
  * @param[in] addr  pointer to a sockaddr structure containing the address to be bound to the socket
  * @param[in] addrlen the length of the sockaddr structure
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int bind(int sockfd, FAR const struct sockaddr *addr, socklen_t addrlen);
  
  /**
  * @brief   requests a connection to be made on a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[in] addr  pointer to a sockaddr structure containing the peer address
  * @param[in] addrlen the length of the sockaddr structure
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int connect(int sockfd, FAR const struct sockaddr *addr, socklen_t addrlen);
  
  /**
  * @brief    listen for socket connections and limit the queue of incoming connections
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[in] backlog  the number of outstanding connections in the socket's listen queue
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int listen(int sockfd, int backlog);
  
  /**
  * @brief   requests a connection to be made on a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[inout] addr  null or pointer to a sockaddr structure where the address of the connecting socket will be returned
  * @param[inout] addrlen on input specifies the length of the supplied sockaddr structure, and on output specifies the length of the stored address.
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);
  
  /**
  * @brief   send a message on a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[in] buf  Pointer to the buffer containing the message to send.
  * @param[in] len the length of the message in bytes.
  * @param[in] flags the type of message transmission
  * @return On success, returns the number of bytes sent, On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  ssize_t send(int sockfd, FAR const void *buf, size_t len, int flags);
  /**
  * @brief   send a message on a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[in] buf  Pointer to the buffer containing the message to send.
  * @param[in] len the length of the message in bytes.
  * @param[in] flags the type of message transmission
  * @param[in] to pointer to a sockaddr structure containing the destination address
  * @param[in] tolen  the length of the sockaddr structure
  * @return On success, returns the number of bytes sent, On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  ssize_t sendto(int sockfd, FAR const void *buf, size_t len, int flags, FAR const struct sockaddr *to, socklen_t tolen);
  
  /**
  * @brief   send a message on a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[out] buf  Points to a buffer where the message should be stored
  * @param[out] len the length in bytes of the buffer
  * @param[in] flags the type of message reception.
  * @return On success, returns  the length of the message in bytes, On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  ssize_t recv(int sockfd, FAR void *buf, size_t len, int flags);
  
  /**
  * @brief   receive a message from a socket
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[out] buf  Pointer to the buffer where the message should be stored.
  * @param[out] len the length of the message in bytes.
  * @param[in] flags the type of message reception
  * @param[inout] from  A null pointer, or pointer to  sockaddr structure in which the sending address is to be stored
  * @param[inout] fromlen  null or the length of the sockaddr structure
  * @return On success, returns the length of the message in bytes, On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  ssize_t recvfrom(int sockfd, FAR void *buf, size_t len, int flags, FAR struct sockaddr *from, FAR socklen_t *fromlen);
  
  /**
  * @brief   shut down socket send and receive operations
  *
  * @param[in] sockfd the file descriptor of the socket
  * @param[in] how the type of shutdown
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int shutdown(int sockfd, int how);
  
  /**
  * @brief   close a socket
  *
  * @param[in] s the file descriptor of the socket
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int closesocket(int s);
  /**
  * @brief   set the socket options
  *
  * @param[in] sockfd the file descriptor of the socket
  * @param[in] level the protocol level
  * @param[in] option the option to be set for the socket
  * @param[in] value pointer to value of the option
  * @param[in] value_len the length of the value
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int setsockopt(int sockfd, int level, int option, FAR const void *value, socklen_t value_len);
  
  /**
  * @brief   get the socket options
  *
  * @param[in] sockfd the file descriptor of the socket
  * @param[in] level the protocol level at which the option resides
  * @param[in] option a single option to be retrieved
  * @param[out] value pointer to value of the option retrieved
  * @param[out] value_len the length of the value retrieved
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int getsockopt(int sockfd, int level, int option, FAR void *value, FAR socklen_t *value_len);
  /**
  * @brief  get the socket name
  *
  * @param[in] sockfd the file descriptor associated with the socket.
  * @param[inout] addr  null or pointer to a sockaddr structure where the address of the local socket will be returned
  * @param[inout] addrlen on input specifies the length of the supplied sockaddr structure, and on output specifies the length of the stored address.
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int getsockname(int sockfd, FAR struct sockaddr *addr, FAR socklen_t *addrlen);
  
  /**
  * @brief  get the name of the peer socket
  *
  * @param[in] s the file descriptor associated with the socket.
  * @param[inout] name  null or pointer to a sockaddr structure where the address of the peer socket will be returned
  * @param[inout] namelen on input specifies the length of the supplied sockaddr structure, and on output specifies the length of the stored address.
  * @return On success, 0 is returned. On failure, -1 is returned.
  * @since Tizen RT v1.0
  */
  int getpeername(int s, struct sockaddr *name, socklen_t *namelen);
  
  #undef EXTERN
  #if defined(__cplusplus)
  }
  #endif
  
  #endif							/* __INCLUDE_SYS_SOCKET_H */
  
  /** @} */// end of NETWORK group
  