/* $XORP: xorp/xrl/interfaces/socket6.xif,v 1.14 2008/04/23 15:22:41 bms Exp $ */

#include <xorp_config.h>

#ifdef HAVE_IPV6


/**
 * Interface implementing basic IPv6 socket functionality.  This interface
 * provides methods for creating and binding sockets, sending data on
 * sockets, and set configuration options on sockets.  It is used together
 * with socket6_user/0.1:
 *
 *    - socket6/0.1	     interface for creating sockets, sending
 *			     data, setting options, etc.
 *
 *    - socket6_user/0.1     interface users of socket6/0.1 should implement
 *			     to receive data and event notifications.
 *
 */
interface socket6/0.1 {

    /**
     * Open a TCP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket4_user/0.1.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    tcp_open			? creator:txt				\
				-> sockid:txt;

    /**
     * Open an UDP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket4_user/0.1.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    udp_open			? creator:txt				\
				-> sockid:txt;

    /**
     * Create a bound TCP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket6_user/0.1.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    tcp_open_and_bind		? creator:txt				\
				& local_addr:ipv6			\
				& local_port:u32			\
				-> sockid:txt;

    /**
     * Create a bound UDP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket6_user/0.1.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    udp_open_and_bind		? creator:txt				\
				& local_addr:ipv6			\
				& local_port:u32			\
				& local_dev:txt			\
				& reuse:u32			\
				-> sockid:txt;

    /**
     * Create a bound UDP multicast socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket6_user/0.1.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     *
     * @param mcast_addr the multicast group address to join.
     *
     * @param ttl the ttl to use for this multicast socket.
     *
     * @param reuse allow other sockets to bind to same multicast group.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    udp_open_bind_join		? creator:txt				\
				& local_addr:ipv6			\
				& local_port:u32			\
				& mcast_addr:ipv6			\
				& ttl:u32				\
				& reuse:bool				\
				-> sockid:txt;

    /**
     * Create a bound and connected TCP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket6_user/0.1.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     *
     * @param remote_addr the address to connect to.
     *
     * @param remote_port the remote port to connect to.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    tcp_open_bind_connect	? creator:txt				\
				& local_addr:ipv6			\
				& local_port:u32			\
				& remote_addr:ipv6			\
				& remote_port:u32			\
				-> sockid:txt;

    /**
     * Create a bound and connected UDP socket.
     *
     * @param creator the Xrl Target instance name of the socket
     *        creator.  The named target must implement socket6_user/0.1.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     *
     * @param remote_addr the address to connect to.
     *
     * @param remote_port the remote port to connect to.
     *
     * @param sockid return parameter that contains unique socket ID when
     *        socket instantiation is successful.
     */
    udp_open_bind_connect	? creator:txt				\
				& local_addr:ipv6			\
				& local_port:u32			\
				& remote_addr:ipv6			\
				& remote_port:u32			\
				-> sockid:txt;

    /**
     * Bind a socket.
     *
     * @param sockid the socket ID of the socket to bind.
     *
     * @param local_addr the interface address to bind socket to.
     *
     * @param local_port the port to bind socket to.
     */
    bind			? sockid:txt                            \
				& local_addr:ipv6                       \
				& local_port:u32;

    /**
     * Join multicast group on already bound socket.
     *
     * @param sockid unique socket ID.
     *
     * @param mcast_addr group to join.
     *
     * @param join_if_addr interface address to perform join on.
     *
     */
    udp_join_group		? sockid:txt				\
				& mcast_addr:ipv6			\
				& join_if_addr:ipv6;

    /**
     * Leave multicast group on already bound socket.
     *
     * @param sockid unique socket ID.
     *
     * @param mcast_addr group to leave.
     *
     * @param leave_if_addr interface address to perform leave on.
     *
     */
    udp_leave_group		? sockid:txt				\
				& mcast_addr:ipv6			\
				& leave_if_addr:ipv6;

    /**
     * Close socket.
     *
     * @param sockid unique socket ID of socket to be closed.
     */
    close			? sockid:txt;

    /**
     * Listen for inbound connections on socket.  When a connection request
     * received the socket creator will receive notification through
     * socket6_user/0.1/inbound_connect_event.
     *
     * @param sockid the unique socket ID of the socket to perform listen.
     *
     * @param backlog the maximum number of pending connections.
     */
    tcp_listen			? sockid:txt				\
				& backlog:u32;

    /**
     * Send data on socket.
     *
     * @param sockid unique socket ID.
     *
     * @param data block of data to be sent.
     */
    send			? sockid:txt				\
				& data:binary;

    /**
     * Send data on socket to a given destination.  The packet is not
     * routed as the forwarding engine sending the packet may not have
     * access to the full routing table.
     *
     * @param sockid unique socket ID.
     *
     * @param remote_addr destination address for data.
     *
     * @param remote_port destination port for data.
     *
     * @param data block of data to be sent.
     */
    send_to			? sockid:txt				\
				& remote_addr:ipv6			\
				& remote_port:u32			\
				& data:binary;

   /**
     * Send data on socket to a given multicast group from a given
     * interface.
     *
     * @param sockid unique socket ID.
     *
     * @param group_addr destination address for data.
     *
     * @param group_port destination port for data.
     *
     * @param ifaddr interface address
     */
    send_from_multicast_if	? sockid:txt				\
				& group_addr:ipv6			\
				& group_port:u32			\
				& ifaddr:ipv6				\
				& data:binary;

    /**
     * Set a named socket option with an integer value.
     *
     * @param sockid unique socket ID.
     *
     * @param optname name of option to be set.  Valid values are:
     * 		"reuseport"
     *		"ttl"
     * 		"multicast_loopback"
     *		"multicast_ttl"
     *
     * @param optval value of option to be set.  If value is logically boolean
     *        then zero represents false and any non-zero value true.
     */
    set_socket_option		? sockid:txt				\
				& optname:txt				\
				& optval:u32;
}

#endif
