/******************************************************/
/* Copyright (C) 2008 Arch Rock Corporation           */
/* License Agreement: refer to LICENSE.txt            */
/*                                                    */
/******************************************************/

#ifndef _ICMP_H
#define _ICMP_H    1

#include <event.h>
#include <sys/socket.h>

typedef struct ping_cbargs
{
  /*! source address of the ping reply */
  sockaddr_in6_t src;
  /*! Received signal strength if \em src is 1-hop away. */
  int8_t rssi;
  /*! Ping delay in milliseconds. */
  uint16_t delay;
  /*! Length of the ping reply in bytes. */
  uint8_t len;
  /*! String buffer that contains a user readable text message
   *  to show the result of the Reply.
   *  For example, "12 bytes from fe80::17:3b00:0:15 rssi=-35 dBm 
   *  delay=135ms" or "Request timed out".
   */
  const char *ping_reply;
  /*! Ping errors:  SUCCESS, ETIMEOUT, ENETUNREACH.  See #ErrnoEnum.*/
  int8_t error;
  /*! True if this is the last signal for ping */
  uint8_t done;
}ping_cbargs_t;


/*! A system call to perform the standard ICMP ping service 
 *  to an unicast IP address or to a link local
 *  multicast address.
 *  
 *  The ping service is either completed by getting a
 *  ping response from the destination or a timeout
 *  notification.  In the case of link local multicast with 
 *  multiple responses, the \em ping_handler() will be invoked
 *  for each ping respond. A timeout notification will always 
 *  be generated to signal the completion of a link local multicast ping.
 *  The \em done field in \em ping_cbargs_t signals the completion
 *  of the ping and thus expires the binding of the callback handler
 *  with the ping call.
 *
 *  @param[in] dst IPv6 address of the desired destination(s) to ping
 *  @param[in] ping_handler continuation callback handler.  If 
 *                          NULL is passed, call will fail.
 *  @param[out] ping_result results of the calls for the
 *                          continatuion callback are stored here.
 *                          if NULL is passed, call will fail
 *  @param[in] context application context
 *  \return 0 if succeed and -1 if fail and errno is set appropriately.
 *
 *  \par Errors:
 *     EBUSY if the underlying system is busy
 *  \par
 *     EOFF if underlying system is off.  (e.g. link interface is off)
 *   \par
 *     EINVAL if invalid parameters are passed
 *
 *  \section ping_callback Callback Descriptions
 *     \subsection ping_handler ping_handler
 *     @param[in] event  Type is PING in #EventsEnum
 *     @param[in] cbargs is \em ping_result in ping()
 *     @param[in] context is \em context in ping()
 *     \return None.
 */
int16_t ping(const char *dst,	     
	     void (*ping_handler)(event_t event,
				  void * cbargs,
				  void * context),
	     ping_cbargs_t *ping_result,
	     void * context);


#endif
