/*****************************************************************************
* Copyright (c) 2005 Digi International Inc., All Rights Reserved
* 
* This software contains proprietary and confidential information of Digi
* International Inc.  By accepting transfer of this copy, Recipient agrees
* to retain this software in confidence, to prevent disclosure to others,
* and to make no use of this software other than that for which it was
* delivered.  This is an unpublished copyrighted work of Digi International
* Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
* prohibited.
* 
* Restricted Rights Legend
*
* Use, duplication, or disclosure by the Government is subject to
* restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
* Technical Data and Computer Software clause at DFARS 252.227-7031 or
* subparagraphs (c)(1) and (2) of the Commercial Computer Software -
* Restricted Rights at 48 CFR 52.227-19, as applicable.
*
* Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
*
*****************************************************************************
*
*  Description
*  ====================================================================
*  This file contains definitions for the NET+OS ARP API.
*
*/

#ifndef naarpapi_h
#define naarpapi_h

#ifdef __cplusplus
extern "C"
{
#endif

#include "sockapi.h"

/*ad*
 * The ARP API provides access to the TCP/IP ARP table. 
 *
 * Use naArpGetEntryByIpAddr routine to search the ARP table by the IP address and retrieve the 
 * physical address.
 *
 * Use naArpGetEntryByPhysAddr routine to search the ARP table by the physical and retrieve the 
 * IP address.
 *
 * @external
 * @category    ArpApi
 * @since 7.4
 * @include 	"naarpapi.h"
 * @platform 	all
 * @library		tcpip
 * @overview    ARP API
*ad*/

/*ad*
 * Retrieves an entry from the ARP cache by looking up the entry by the IP address 
 *
 * @external
 * @include 	"naarpapi.h"
 * @category    ArpApi
 * @since 7.4
 *
 * @param arpIpAddr     Pointer to a structure, holding an IP address. The only supported address. 
 *                      family is AF_INET.
 * @param ipAddrlen     Size of the arpIpAddr buffer in bytes.
 * @param physAddr      The pointer to the buffer where to store the physical address.
 * @param physAddrLen   The pointer to the size of the physical address in bytes. On input must point to 
 *                      the size of physAddr buffer. On output is filled in with the actual size of the 
 *                      physical address.
 *
 * @return 0                ARP entry successfully retrieved.
 * @return EINVAL           Invalid arguments.
 * @return EAFNOSUPPORT     Address family is not AF_INET.
 * @return ENOENT           No ARP entry found with this IP address.
 *
 * @note An argument used for the arpIpAddr parameter must be struct sockaddr_in type, with the sin_family
 *       field set to AF_INET, sin_addr field having an IP address.
 *
 * <example>
 *
 * unsigned char phys_addr[6]; 
 * struct   sockaddr_in fsin;
 * int      result;
 * size_t   phys_addr_len = 6;
 * 
 * fsin.sin_family = AF_INET;
 * fsin.sin_addr.s_addr = NAInet_addr("7.92.187.163");
 *
 * result = naArpGetEntryByIpAddr((struct sockaddr *) &fsin, sizeof fsin, phys_addr, &phys_addr_len);
 * 
 * </example>
 *
 * @see @link naArpGetEntryByPhysAddr
*ad*/
int naArpGetEntryByIpAddr(const struct sockaddr * arpIpAddr, size_t ipAddrlen, unsigned char * physAddr, size_t * physAddrLen);


/*ad*
 * Retrieves an entry from the ARP cache by looking up the entry by the physical address 
 *
 * @external
 * @include 	"naarpapi.h"
 * @category    ArpApi
 * @since 7.4
 *
 * @param physAddr      The pointer to the physical address.
 * @param physAddrLen   The size of the physical address in bytes. 
 * @param arpIpAddr     Pointer to a buffer where to store the IP address. The only supported address 
 *                      family is AF_INET. 
 * @param ipAddrlen     Pointer to the size of the arpIpAddr buffer in bytes. 
 *
 * @return 0                ARP entry successfully retrieved.
 * @return EINVAL           Invalid arguments.
 * @return ENOENT           No ARP entry found with this IP address.
 *
 * @note An argument used for the arpIpAddr parameter must be struct sockaddr_in type, with the sin_family
 *       field set to AF_INET.
 *
 * <example>
 *
 * unsigned  char phys_addr[6] = {0x0, 0x40, 0x9d, 0x43, 0x35, 0x97}; 
 * struct    sockaddr_in fsin;
 * size_t    fsin_len = sizeof fsin;
 * int       result;
 * 
 * fsin.sin_family = AF_INET;
 *
 * result = naArpGetEntryByPhysAddr(phys_addr, 6, (struct sockaddr *) &fsin, &fsin_len);
 * 
 * </example>
 *
 * @see @link naArpGetEntryByIpAddr
*ad*/
int naArpGetEntryByPhysAddr(const unsigned char * physAddr, size_t physAddrLen, struct sockaddr * arpIpAddr, size_t * ipAddrlen);

/*ad*
 * Flushes ARP cache 
 *
 * @external
 * @include 	"naarpapi.h"
 * @category    ArpApi
 * @since 7.4
 *
 * @return 0             Completed successfully.
 * @return ENOMEM        Could not allocate required temporary buffers.
 *
*ad*/
int naArpFlush(void);

#ifdef __cplusplus
}
#endif
#endif
