/*
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.datagram;

import io.vertx.codegen.annotations.Nullable;
import io.vertx.core.AsyncResult;
import io.vertx.core.Handler;
import io.vertx.core.buffer.Buffer;
import io.vertx.codegen.annotations.CacheReturn;
import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.metrics.Measured;
import io.vertx.core.net.SocketAddress;
import io.vertx.core.streams.ReadStream;
import io.vertx.core.streams.WriteStream;

A datagram socket can be used to send DatagramPacket's to remote datagram servers and receive DatagramPackets . 

Usually you use a datagram socket to send UDP over the wire. UDP is connection-less which means you are not connected
to the remote peer in a persistent way. Because of this you have to supply the address and port of the remote peer
when sending data.

You can send data to ipv4 or ipv6 addresses, which also include multicast addresses.

Please consult the documentation for more information on datagram sockets.
Author:
Norman Maurer/**
 * A datagram socket can be used to send {@link DatagramPacket}'s to remote datagram servers
 * and receive {@link DatagramPacket}s .
 * <p>
 * Usually you use a datagram socket to send UDP over the wire. UDP is connection-less which means you are not connected
 * to the remote peer in a persistent way. Because of this you have to supply the address and port of the remote peer
 * when sending data.
 * <p>
 * You can send data to ipv4 or ipv6 addresses, which also include multicast addresses.
 * <p>
 * Please consult the documentation for more information on datagram sockets.
 *
 * @author <a href="mailto:nmaurer@redhat.com">Norman Maurer</a>
 */
@VertxGen
public interface DatagramSocket extends ReadStream<DatagramPacket>, Measured {

  
Write the given Buffer to the SocketAddress. The Handler will be notified once the write completes. 
Params:
packet –  the Buffer to write
port –  the host port of the remote peer
host –  the host address of the remote peer
handler –  the Handler to notify once the write completes.
Returns:
a reference to this, so the API can be used fluently/**
   * Write the given {@link io.vertx.core.buffer.Buffer} to the {@link io.vertx.core.net.SocketAddress}.
   * The {@link io.vertx.core.Handler} will be notified once the write completes.
   *
   * @param packet  the {@link io.vertx.core.buffer.Buffer} to write
   * @param port  the host port of the remote peer
   * @param host  the host address of the remote peer
   * @param handler  the {@link io.vertx.core.Handler} to notify once the write completes.
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket send(Buffer packet, int port, String host, Handler<AsyncResult<DatagramSocket>> handler);

  
Returns a WriteStream<Buffer> able to send Buffer to the SocketAddress. 
Params:
port – the port of the remote peer
host – the host address of the remote peer
Returns:
the write stream for sending packets/**
   * Returns a {@code WriteStream<Buffer>} able to send {@link Buffer} to the
   * {@link io.vertx.core.net.SocketAddress}.
   *
   * @param port the port of the remote peer
   * @param host the host address of the remote peer
   * @return the write stream for sending packets
   */
  WriteStream<Buffer> sender(int port, String host);

  
Write the given String to the SocketAddress using UTF8 encoding. The Handler will be notified once the write completes. 
Params:
str –  the String to write
port –  the host port of the remote peer
host –  the host address of the remote peer
handler –  the Handler to notify once the write completes.
Returns:
a reference to this, so the API can be used fluently/**
   * Write the given {@link String} to the {@link io.vertx.core.net.SocketAddress} using UTF8 encoding.
   * The {@link Handler} will be notified once the write completes.
   *
   * @param str   the {@link String} to write
   * @param port  the host port of the remote peer
   * @param host  the host address of the remote peer
   * @param handler  the {@link io.vertx.core.Handler} to notify once the write completes.
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket send(String str, int port, String host, Handler<AsyncResult<DatagramSocket>> handler);

  
Write the given String to the SocketAddress using the given encoding. The Handler will be notified once the write completes. 
Params:
str –  the String to write
enc –  the charset used for encoding
port –  the host port of the remote peer
host –  the host address of the remote peer
handler –  the Handler to notify once the write completes.
Returns:
a reference to this, so the API can be used fluently/**
   * Write the given {@link String} to the {@link io.vertx.core.net.SocketAddress} using the given encoding.
   * The {@link Handler} will be notified once the write completes.
   *
   * @param str  the {@link String} to write
   * @param enc  the charset used for encoding
   * @param port  the host port of the remote peer
   * @param host  the host address of the remote peer
   * @param handler  the {@link io.vertx.core.Handler} to notify once the write completes.
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket send(String str, String enc, int port, String host, Handler<AsyncResult<DatagramSocket>> handler);

  
Closes the DatagramSocket implementation asynchronous and notifies the handler once done. 
Params:
handler –  the handler to notify once complete/**
   * Closes the {@link io.vertx.core.datagram.DatagramSocket} implementation asynchronous
   * and notifies the handler once done.
   *
   * @param handler  the handler to notify once complete
   */
  void close(Handler<AsyncResult<Void>> handler);

  
Closes the DatagramSocket. The close itself is asynchronous. /**
   * Closes the {@link io.vertx.core.datagram.DatagramSocket}. The close itself is asynchronous.
   */
  void close();

  
Return the SocketAddress to which this DatagramSocket is bound. 
Returns:
the socket address/**
   * Return the {@link io.vertx.core.net.SocketAddress} to which
   * this {@link io.vertx.core.datagram.DatagramSocket} is bound.
   *
   * @return the socket address
   */
  @CacheReturn
  SocketAddress localAddress();

  
Joins a multicast group and listens for packets send to it. The Handler is notified once the operation completes. 
Params:
multicastAddress –  the address of the multicast group to join
handler –  then handler to notify once the operation completes
Returns:
a reference to this, so the API can be used fluently/**
   * Joins a multicast group and listens for packets send to it.
   * The {@link Handler} is notified once the operation completes.
   *
   * @param multicastAddress  the address of the multicast group to join
   * @param  handler  then handler to notify once the operation completes
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket listenMulticastGroup(String multicastAddress, Handler<AsyncResult<DatagramSocket>> handler);

  
Joins a multicast group and listens for packets send to it on the given network interface. The Handler is notified once the operation completes. 
Params:
multicastAddress –  the address of the multicast group to join
networkInterface –  the network interface on which to listen for packets.
source –  the address of the source for which we will listen for multicast packets
handler –  then handler to notify once the operation completes
Returns:
a reference to this, so the API can be used fluently/**
   * Joins a multicast group and listens for packets send to it on the given network interface.
   * The {@link Handler} is notified once the operation completes.
   *
   * @param  multicastAddress  the address of the multicast group to join
   * @param  networkInterface  the network interface on which to listen for packets.
   * @param  source  the address of the source for which we will listen for multicast packets
   * @param  handler  then handler to notify once the operation completes
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket listenMulticastGroup(String multicastAddress, String networkInterface, @Nullable String source,
                                      Handler<AsyncResult<DatagramSocket>> handler);

  
Leaves a multicast group and stops listening for packets send to it. The Handler is notified once the operation completes. 
Params:
multicastAddress –  the address of the multicast group to leave
handler –  then handler to notify once the operation completes
Returns:
a reference to this, so the API can be used fluently/**
   * Leaves a multicast group and stops listening for packets send to it.
   * The {@link Handler} is notified once the operation completes.
   *
   * @param multicastAddress  the address of the multicast group to leave
   * @param handler  then handler to notify once the operation completes
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket unlistenMulticastGroup(String multicastAddress, Handler<AsyncResult<DatagramSocket>> handler);

  
Leaves a multicast group and stops listening for packets send to it on the given network interface. The Handler is notified once the operation completes. 
Params:
multicastAddress –  the address of the multicast group to join
networkInterface –  the network interface on which to listen for packets.
source –  the address of the source for which we will listen for multicast packets
handler – the handler to notify once the operation completes
Returns:
 a reference to this, so the API can be used fluently/**
   * Leaves a multicast group and stops listening for packets send to it on the given network interface.
   * The {@link Handler} is notified once the operation completes.
   *
   * @param  multicastAddress  the address of the multicast group to join
   * @param  networkInterface  the network interface on which to listen for packets.
   * @param  source  the address of the source for which we will listen for multicast packets
   * @param  handler the handler to notify once the operation completes
   * @return  a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket unlistenMulticastGroup(String multicastAddress, String networkInterface, @Nullable String source,
                                        Handler<AsyncResult<DatagramSocket>> handler);

  
Block the given address for the given multicast address and notifies the Handler once the operation completes. 
Params:
multicastAddress –  the address for which you want to block the source address
sourceToBlock –  the source address which should be blocked. You will not receive an multicast packets
                      for it anymore.
handler –  the handler to notify once the operation completes
Returns:
 a reference to this, so the API can be used fluently/**
   * Block the given address for the given multicast address and notifies the {@link Handler} once
   * the operation completes.
   *
   * @param multicastAddress  the address for which you want to block the source address
   * @param sourceToBlock  the source address which should be blocked. You will not receive an multicast packets
   *                       for it anymore.
   * @param handler  the handler to notify once the operation completes
   * @return  a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket blockMulticastGroup(String multicastAddress, String sourceToBlock,
                                     Handler<AsyncResult<DatagramSocket>> handler);

  
Block the given address for the given multicast address on the given network interface and notifies the Handler once the operation completes. 
Params:
multicastAddress –  the address for which you want to block the source address
networkInterface –  the network interface on which the blocking should occur.
sourceToBlock –  the source address which should be blocked. You will not receive an multicast packets
                       for it anymore.
handler –  the handler to notify once the operation completes
Returns:
 a reference to this, so the API can be used fluently/**
   * Block the given address for the given multicast address on the given network interface and notifies
   * the {@link Handler} once the operation completes.
   *
   * @param  multicastAddress  the address for which you want to block the source address
   * @param  networkInterface  the network interface on which the blocking should occur.
   * @param  sourceToBlock  the source address which should be blocked. You will not receive an multicast packets
   *                        for it anymore.
   * @param  handler  the handler to notify once the operation completes
   * @return  a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket blockMulticastGroup(String multicastAddress, String networkInterface, String sourceToBlock,
                                     Handler<AsyncResult<DatagramSocket>> handler);

  
Start listening on the given port and host. The handler will be called when the socket is listening.
Params:
port –  the port to listen on
host –  the host to listen on
handler –  the handler will be called when listening
Returns:
 a reference to this, so the API can be used fluently/**
   * Start listening on the given port and host. The handler will be called when the socket is listening.
   *
   * @param port  the port to listen on
   * @param host  the host to listen on
   * @param handler  the handler will be called when listening
   * @return  a reference to this, so the API can be used fluently
   */
  @Fluent
  DatagramSocket listen(int port, String host, Handler<AsyncResult<DatagramSocket>> handler);

  @Override
  DatagramSocket pause();

  @Override
  DatagramSocket resume();

  @Override
  DatagramSocket fetch(long amount);

  @Override
  DatagramSocket endHandler(Handler<Void> endHandler);

  @Override
  DatagramSocket handler(Handler<DatagramPacket> handler);

  @Override
  DatagramSocket exceptionHandler(Handler<Throwable> handler);

}