struct netstack* netstack_create(const netstack_opts* opts);
int netstack_destroy(struct netstack* ns);

typedef enum {
  NETSTACK_MOD, // a non-destructive event about an object
  NETSTACK_DEL, // an object that is going away
} netstack_event_e;

// Callback types for various events. Even though routes, addresses etc. can be
// reached through a netstack_iface, they each get their own type of callback.
typedef void (*netstack_iface_cb)(const struct netstack_iface*, netstack_event_e, void*);
typedef void (*netstack_addr_cb)(const struct netstack_addr*, netstack_event_e, void*);
typedef void (*netstack_route_cb)(const struct netstack_route*, netstack_event_e, void*);
typedef void (*netstack_neigh_cb)(const struct netstack_neigh*, netstack_event_e, void*);

// Policy for initial object dump. _ASYNC will cause events for existing
// objects, but netstack_create() may return before they've been received.
// _BLOCK blocks netstack_create() from returning until all initial enumeration
// events have been received. _NONE inhibits initial enumeration.
typedef enum {
  NETSTACK_INITIAL_EVENTS_ASYNC,
  NETSTACK_INITIAL_EVENTS_BLOCK,
  NETSTACK_INITIAL_EVENTS_NONE,
} netstack_initial_e;

// The default for all members is false or the appropriate zero representation.
// It is invalid to supply a non-NULL curry together with a NULL callback for
// any type. It is invalid to supply no callbacks together with all notracks.
typedef struct netstack_opts {
  // a given curry may be non-NULL only if the corresponding cb is also NULL.
  netstack_iface_cb iface_cb;
  void* iface_curry;
  netstack_addr_cb addr_cb;
  void* addr_curry;
  netstack_route_cb route_cb;
  void* route_curry;
  netstack_neigh_cb neigh_cb;
  void* neigh_curry;
  // If set, do not cache the corresponding type of object
  bool iface_notrack, addr_notrack, route_notrack, neigh_notrack;
  netstack_initial_e initial_events; // policy for initial object enumeration
} netstack_opts;

// Take a reference on some netstack iface for read-only use in the client.
// There is no copy, but the object still needs to be freed by a call to
// netstack_iface_abandon().
const struct netstack_iface* netstack_iface_share_byname(struct netstack* ns, const char* name);
const struct netstack_iface* netstack_iface_share_byidx(struct netstack* ns, int idx);

// Copy out a netstack iface for arbitrary use in the client. This is a
// heavyweight copy, and must be freed using netstack_iface_destroy(). You
// would usually be better served by netstack_iface_share_*().
struct netstack_iface* netstack_iface_copy_byname(struct netstack* ns, const char* name);
struct netstack_iface* netstack_iface_copy_byidx(struct netstack* ns, int idx);

// Copy/share a netstack_iface to which we already have a handle, for
// instance directly from the callback context. This is faster than the
// alternatives, as it needn't perform a lookup.
const struct netstack_iface* netstack_iface_share(const struct netstack_iface* ni);
struct netstack_iface* netstack_iface_copy(const struct netstack_iface* ni);

// Release a netstack_iface acquired from the netstack through either a copy or
// a share operation. Note that while the signature claims constness, ns will
// actually presumably be mutated (via alias). It is thus imperative that the
// passed object not be used again by the caller!
void netstack_iface_abandon(const struct netstack_iface* ni);

// Count of interfaces in the active store, and bytes used to represent them in
// total. If iface_notrack is set, these will always return 0.
unsigned netstack_iface_count(const struct netstack* ns);
uint64_t netstack_iface_bytes(const netstack* ns);

// State for streaming enumerations (enumerations taking place over several
// calls). It's exposed in this header so that callers can easily define one on
// their stacks. Don't mess with it. Zero it out to start a new enumeration.
typedef struct netstack_enumerator {
  uint32_t nonce;
  uint32_t slot;
  struct netstack_iface* hnext;
} netstack_enumerator;

// Enumerate up to n netstack_ifaces via copy. offsets must have space for at
// least n elements, which will serve as offsets into objs. objs is a flat
// array of size obytes. streamer ought point to a zero-initialized
// netstack_enumerator to begin an enumeration operation. If
// netstack_iface_enumerate() is called again using this same streamer, the
// enumeration picks up where it left off. A NULL streamer is interpreted as a
// request for atomic enumeration; if there is not sufficient space to copy all
// objects, it is an error, and the copying will be aborted as soon as
// possible. Unlike other errors, n and obytes will be updated in this case to
// reflect the current necessary values.
//
// Returns -1 on error, due to invalid parameters, insufficient space for an
// atomic enumeraion, or failure to resume an enumeration (this can happen if
// too much has changed since the previous call--enumerations aren't really
// suitable for highly dynamic environments). No parameters are modified in
// this case (save the atomic case, as noted above). Otherwise, the number of objects
// copied r is returned, r <= the original *n. n is set to the number of
// objects remaining. obytes is set to the bytes required to copy the remaning
// objects. streamer is updated, if appropriate. The first r values of offsets
// give valid byte offsets into objs, and a (suitably-aligned) network_iface is
// present at each such offset. Their associated buffers are also present in
// objs. The pointers and bookkeeping within the netstack_ifaces have been
// updated so that the resulting objects can be used with the standard
// netstack_iface API. There is no need to call netstack_iface_abandon() on
// these objects.
//
// An enumeration operation is thus successfully terminated iff a non-negative
// number is returned, and *n and *obytes have both been set to 0. Note that
// a 0 could be returned without completion if objs is too small to copy the
// next object; in this case, neither *n nor *obytes would be 0.
int netstack_iface_enumerate(const struct netstack* ns,
                             uint32_t* offsets, int* n,
                             void* objs, size_t* obytes,
                             netstack_enumerator* streamer);

// name must be at least IFNAMSIZ bytes. returns NULL if no name was reported,
// or the name was greater than IFNAMSIZ-1 bytes (should never happen).
char* netstack_iface_name(const struct netstack_iface* ni, char* name);

unsigned netstack_iface_type(const struct netstack_iface* ni);
unsigned netstack_iface_family(const struct netstack_iface* ni);
int netstack_iface_index(const struct netstack_iface* ni);
unsigned netstack_iface_flags(const struct netstack_iface* ni);

static inline bool netstack_iface_up(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_UP;
}

// Has a valid broadcast address been configured?
static inline bool netstack_iface_broadcast(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_BROADCAST;
}

// Is this a loopback device?
static inline bool netstack_iface_loopback(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_LOOPBACK;
}

// Is this a point-to-point link?
static inline bool netstack_iface_pointtopoint(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_POINTOPOINT;
}

// Does this link lack ARP?
static inline bool netstack_iface_noarp(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_NOARP;
}

// Is the interface in promiscuious mode?
static inline bool netstack_iface_promisc(const struct netstack_iface* ni){
  return netstack_iface_flags(ni) & IFF_PROMISC;
}

// pass in the maximum number of bytes available for copying the link-layer
// address. if this is sufficient, the actual number of bytes copied will be
// stored to this variable. otherwise, NULL will be returned.
static inline void*
netstack_iface_l2addr(const struct netstack_iface* ni, void* buf, size_t* len){
  const struct rtattr* rta = netstack_iface_attr(ni, IFLA_ADDRESS);
  return netstack_rtattrcpy(rta, buf, len) ? buf : NULL;
}

// same deal as netstack_iface_l2addr(), but for the broadcast link-layer
// address (if one exists).
static inline void*
netstack_iface_l2broadcast(const struct netstack_iface* ni, void* buf, size_t* len){
  const struct rtattr* rta = netstack_iface_attr(ni, IFLA_BROADCAST);
  return netstack_rtattrcpy(rta, buf, len) ? buf : NULL;
}

// Returns the MTU as reported by netlink, or 0 if none was reported.
static inline uint32_t
netstack_iface_mtu(const struct netstack_iface* ni){
  const struct rtattr* rta = netstack_iface_attr(ni, IFLA_MTU);
  uint32_t ret;
  return netstack_rtattrcpy_exact(rta, &ret, sizeof(ret)) ? ret : 0;
}

// Returns the link type (as opposed to the device type, as returned by
// netstack_iface_type
static inline int
netstack_iface_link(const struct netstack_iface* ni){
  const struct rtattr* rta = netstack_iface_attr(ni, IFLA_LINK);
  int ret;
  return netstack_rtattrcpy_exact(rta, &ret, sizeof(ret)) ? ret : 0;
}

// Returns the queuing discipline, or NULL if none was reported. The return is
// heap-allocated, and must be free()d by the caller.
char* netstack_iface_qdisc(const struct netstack_iface* ni);

// Refresh stats for all interfaces. Blocking call, as it involves writing to
// and reading a reply from netlink. Following a success,
// netstack_iface_stats() can be used to get the new stats.
int netstack_iface_stats_refresh(struct netstack*);

// Returns interface stats if they were reported, filling in the stats object
// and returning 0. Returns -1 if there were no stats.
static inline bool
netstack_iface_stats(const struct netstack_iface* ni, struct rtnl_link_stats64* stats){
  const struct rtattr* rta = netstack_iface_attr(ni, IFLA_STATS64);
  return netstack_rtattrcpy_exact(rta, stats, sizeof(*stats));
}

// Get the nth IRQ of the device, or -1 on failure. Currently only works for
// directly-attached PCIe NICs (i.e. we don't look up xhci_hcd IRQs for a USB
// device) using MSI.
int netstack_iface_irq(const struct netstack_iface* ni, unsigned qidx);

// Get the number of MSI interrupts for the device.
unsigned netstack_iface_irqcount(const struct netstack_iface* ni);

const struct rtattr* netstack_addr_attr(const struct netstack_addr* na, int attridx);
unsigned netstack_addr_family(const struct netstack_addr* na);
unsigned netstack_addr_prefixlen(const struct netstack_addr* na);
unsigned netstack_addr_flags(const struct netstack_addr* na);
unsigned netstack_addr_scope(const struct netstack_addr* na);
int netstack_addr_index(const struct netstack_addr* na);

// Returns true iff there is an IFA_ADDRESS layer 3 address associated with this
// entry, *and* it can be transformed into a presentable string, *and* buf is
// large enough to hold the result. buflen ought be at least INET6_ADDRSTRLEN.
// family will hold the result of netstack_addr_family() (assuming that an
// IFA_ADDRESS rtattr was indeed present).
static inline char*
netstack_addr_addressstr(const struct netstack_addr* na, char* buf,
                         size_t buflen, unsigned* family){
  const struct rtattr* narta = netstack_addr_attr(na, IFA_ADDRESS);
  if(narta == NULL){
    return NULL;
  }
  *family = netstack_addr_family(na);
  if(!netstack_rtattr_l3addrstr(*family, narta, buf, buflen)){
    return NULL;
  }
  return buf;
}

// Returns true iff there is an IFA_LOCAL layer 3 address associated with this
// entry, *and* it can be transformed into a presentable string, *and* buf is
// large enough to hold the result. buflen ought be at least INET6_ADDRSTRLEN.
// family will hold the result of netstack_addr_family() (assuming that an
// IFA_LOCAL rtattr was indeed present).
static inline char*
netstack_addr_localstr(const struct netstack_addr* na, char* buf,
                       size_t buflen, unsigned* family){
  const struct rtattr* narta = netstack_addr_attr(na, IFA_LOCAL);
  if(narta == NULL){
    return NULL;
  }
  *family = netstack_addr_family(na);
  if(!netstack_rtattr_l3addrstr(*family, narta, buf, buflen)){
    return NULL;
  }
  return buf;
}

// Returns the address label, or NULL if none was reported. The return is
// heap-allocated, and must be free()d by the caller.
char* netstack_addr_label(const struct netstack_addr* na);

// Returns address cacheinfo if they were reported, filling in the cinfo object
// and returning 0. Returns -1 if there was no such info.
static inline bool
netstack_addr_cacheinfo(const struct netstack_addr* na, struct ifa_cacheinfo* cinfo){
  const struct rtattr* rta = netstack_addr_attr(na, IFA_CACHEINFO);
  return netstack_rtattrcpy_exact(rta, cinfo, sizeof(*cinfo));
}

const struct rtattr* netstack_route_attr(const struct netstack_route* nr, int attridx);
unsigned netstack_route_family(const struct netstack_route* nr);
unsigned netstack_route_dst_len(const struct netstack_route* nr);
unsigned netstack_route_src_len(const struct netstack_route* nr);
unsigned netstack_route_tos(const struct netstack_route* nr);
// Routing tables are indexed 0-255
unsigned netstack_route_table(const struct netstack_route* nr);
unsigned netstack_route_protocol(const struct netstack_route* nr);
unsigned netstack_route_scope(const struct netstack_route* nr);
unsigned netstack_route_type(const struct netstack_route* nr);
unsigned netstack_route_flags(const struct netstack_route* nr);

static inline bool netstack_route_notify(const struct netstack_route* nr){
  return netstack_route_flags(nr) & RTM_F_NOTIFY;
}

// Was the route cloned from another route?
static inline bool netstack_route_cloned(const struct netstack_route* nr){
  return netstack_route_flags(nr) & RTM_F_CLONED;
}

static inline bool netstack_route_equalize(const struct netstack_route* nr){
  return netstack_route_flags(nr) & RTM_F_EQUALIZE;
}

static inline bool
netstack_route_str(const struct netstack_route* nr, int attr, char* buf,
                   size_t buflen, unsigned* family){
  const struct rtattr* nrrta = netstack_route_attr(nr, attr);
  if(nrrta == NULL){
    return false;
  }
  *family = netstack_route_family(nr);
  if(!netstack_rtattr_l3addrstr(*family, nrrta, buf, buflen)){
    return false;
  }
  return true;
}

static inline bool netstack_route_dststr(const struct netstack_route* nr,
                                         char* buf, size_t buflen,
                                         unsigned* family){
  return netstack_route_str(nr, RTA_DST, buf, buflen, family);
}

static inline bool netstack_route_srcstr(const struct netstack_route* nr,
                                         char* buf, size_t buflen,
                                         unsigned* family){
  return netstack_route_str(nr, RTA_SRC, buf, buflen, family);
}

static inline bool netstack_route_gatewaystr(const struct netstack_route* nr,
                                             char* buf, size_t buflen,
                                             unsigned* family){
  return netstack_route_str(nr, RTA_GATEWAY, buf, buflen, family);
}

static inline int
netstack_route_intattr(const struct netstack_route* nr, int attr){
  const struct rtattr* rt = netstack_route_attr(nr, attr);
  int ret = 0;
  if(rt && RTA_PAYLOAD(rt) == sizeof(ret)){
    memcpy(&ret, RTA_DATA(rt), RTA_PAYLOAD(rt));
  }
  return ret;
}

static inline int
netstack_route_iif(const struct netstack_route* nr){
  return netstack_route_intattr(nr, RTA_IIF);
}

static inline int
netstack_route_oif(const struct netstack_route* nr){
  return netstack_route_intattr(nr, RTA_OIF);
}

static inline int
netstack_route_priority(const struct netstack_route* nr){
  return netstack_route_intattr(nr, RTA_PRIORITY);
}

static inline int
netstack_route_metric(const struct netstack_route* nr){
  return netstack_route_intattr(nr, RTA_METRICS);
}

static inline const char*
netstack_route_typestr(unsigned rtype){
  switch(rtype){
    case RTN_UNSPEC: return "none";
    case RTN_UNICAST: return "unicast";
    case RTN_LOCAL: return "local";
    case RTN_BROADCAST: return "broadcast";
    case RTN_ANYCAST: return "anycast";
    case RTN_MULTICAST: return "multicast";
    case RTN_BLACKHOLE: return "blackhole";
    case RTN_UNREACHABLE: return "unreachable";
    case RTN_PROHIBIT: return "prohibit";
    case RTN_THROW: return "throw";
    case RTN_NAT: return "nat";
    case RTN_XRESOLVE: return "xresolve";
    default: return "?";
  }
}

static inline const char*
netstack_route_scopestr(unsigned scope){
  switch(scope){
    case RT_SCOPE_UNIVERSE: return "global"; // global route
    case RT_SCOPE_SITE: return "site"; // interior route in the local AS
    case RT_SCOPE_LINK: return "link"; // route on this link
    case RT_SCOPE_HOST: return "host"; // route on the local host
    case RT_SCOPE_NOWHERE: return "nowhere"; // destination doesn't exist
    default: return "?";
  }
}

static inline const char*
netstack_route_protstr(unsigned proto){
  switch(proto){
    case RTPROT_UNSPEC: return "unknown";
    case RTPROT_REDIRECT: return "icmp";
    case RTPROT_KERNEL: return "kernel";
    case RTPROT_BOOT: return "boot";
    case RTPROT_STATIC: return "admin";
    case RTPROT_GATED: return "gated";
    case RTPROT_RA: return "rdisc/nd";
    case RTPROT_MRT: return "meritmrt";
    case RTPROT_ZEBRA: return "zebra";
    case RTPROT_BIRD: return "bird";
    case RTPROT_DNROUTED: return "decnet";
    case RTPROT_XORP: return "xdrp";
    case RTPROT_NTK: return "netsukuku";
    case RTPROT_DHCP: return "dhcp";
    case RTPROT_MROUTED: return "mcastd";
    case RTPROT_BABEL: return "babeld";
    case RTPROT_BGP: return "bgp";
    case RTPROT_ISIS: return "isis";
    case RTPROT_OSPF: return "ospf";
    case RTPROT_RIP: return "rip";
    case RTPROT_EIGRP: return "eigrp";
    default: return "?";
  }
}

const struct rtattr* netstack_neigh_attr(const struct netstack_neigh* nn, int attridx);
int netstack_neigh_index(const struct netstack_neigh* nn);
int netstack_neigh_family(const struct netstack_neigh* nn); // always AF_UNSPEC
unsigned netstack_neigh_flags(const struct netstack_neigh* nn);

static inline bool
netstack_neigh_proxyarp(const struct netstack_neigh* nn){
  return netstack_neigh_flags(nn) & NTF_PROXY;
}

static inline bool
netstack_neigh_ipv6router(const struct netstack_neigh* nn){
  return netstack_neigh_flags(nn) & NTF_ROUTER;
}

unsigned netstack_neigh_type(const struct netstack_neigh* nn);
// A bitmask of NUD_{INCOMPLETE, REACHABLE, STALE, DELAY, PROBE, FAILED,
//                   NOARP, PERMANENT}
unsigned netstack_neigh_state(const struct netstack_neigh* nn);

// Returns true iff there is an NDA_DST layer 3 address associated with this
// entry, *and* it can be transformed into a presentable string, *and* buf is
// large enough to hold the result. buflen ought be at least INET6_ADDRSTRLEN.
// family will hold the result of netstack_neigh_family() (assuming that an
// NDA_DST rtattr was indeed present).
static inline bool netstack_neigh_l3addrstr(const struct netstack_neigh* nn,
                                            char* buf, size_t buflen,
                                            unsigned* family){
  const struct rtattr* nnrta = netstack_neigh_attr(nn, NDA_DST);
  if(nnrta == NULL){
    return false;
  }
  *family = netstack_neigh_family(nn);
  if(!l3addrstr(*family, nnrta, buf, buflen)){
    return false;
  }
  return true;
}

// Returns true iff there is an NDA_LLADDR layer 2 address associated with this
// entry, *and* buf is large enough to hold it. buflen ought generally be at
// least ETH_ALEN bytes.
static inline bool netstack_neigh_l2addr(const struct netstack_neigh* nn,
                                         void* buf, size_t buflen){
  const struct rtattr* l2rta = netstack_neigh_attr(nn, NDA_LLADDR);
  if(l2rta == NULL){
    return false;
  }
  if(buflen < RTA_PAYLOAD(l2rta)){
    return false;
  }
  memcpy(buf, RTA_DATA(l2rta), RTA_PAYLOAD(l2rta));
  return true;
}

// Returns non-NULL iff there is an NDA_LLADDR layer 2 address associated with
// this entry, *and* it can be transformed into a presentable string, *and*
// memory is successfully allocated to hold the result. The result must in that
// case be free()d by the caller.
static inline char* netstack_neigh_l2addrstr(const struct netstack_neigh* nn){
  const struct rtattr* l2rta = netstack_neigh_attr(nn, NDA_LLADDR);
  if(l2rta == NULL){
    return NULL;
  }
  char* llstr = netstack_l2addrstr(netstack_neigh_type(nn),
                                   RTA_PAYLOAD(l2rta), RTA_DATA(l2rta));
  return llstr;
}

// Returns true if an NDA_CACHEINFO rtattr is present, in which case cinfo will
// be filled in with the cache statistics for this entry.
static inline bool netstack_neigh_cachestats(const struct netstack_neigh* nn,
                                             struct nda_cacheinfo* cinfo){
  const struct rtattr* rta = netstack_neigh_attr(nn, NDA_CACHEINFO);
  if(rta == NULL){
    return false;
  }
  memcpy(cinfo, RTA_DATA(rta), RTA_PAYLOAD(rta));
  return true;
}

typedef struct netstack_stats {
  // Current counts of each object class
  unsigned ifaces, addrs, routes, neighs;
  // Events for each object class (dumps   creations   changes   deletions)
  uintmax_t iface_events, addr_events, route_events, neigh_events;
  // The number of times a lookup   share or lookup   copy succeeded
  uintmax_t lookup_shares, lookup_copies;
  // Number of shares which have been invalidated but not destroyed
  uintmax_t zombie_shares;
  // The number of times the user looked up a key and it didn't exist
  uintmax_t lookup_failures;
  uintmax_t netlink_errors; // number of nlmsgerrs received from netlink
  uintmax_t user_callbacks_total; // number of times we've called back
} netstack_stats;