fnet_arp.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2016 by Andrey Butok. FNET Community.
00004 *
00005 ***************************************************************************
00006 *
00007 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00008 *  not use this file except in compliance with the License.
00009 *  You may obtain a copy of the License at
00010 *
00011 *  http://www.apache.org/licenses/LICENSE-2.0
00012 *
00013 *  Unless required by applicable law or agreed to in writing, software
00014 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00015 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016 *  See the License for the specific language governing permissions and
00017 *  limitations under the License.
00018 *
00019 **********************************************************************/
00020 /*!
00021 * @brief ARP protocol Public API
00022 *
00023 ***************************************************************************/
00024 
00025 #ifndef _FNET_ARP_H_
00026 
00027 #define _FNET_ARP_H_
00028 
00029 #if FNET_CFG_IP4 || defined(__DOXYGEN__)
00030 
00031 
00032 /*! @addtogroup fnet_arp
00033 * Address Resolution Protocol (ARP)
00034 */
00035 /*! @{ */
00036 
00037 /**************************************************************************/ /*!
00038  * @brief ARP cache entry information structure.
00039  * @see fnet_arp_get_entry()
00040  ******************************************************************************/
00041 FNET_COMP_PACKED_BEGIN
00042 typedef struct fnet_arp_entry_info
00043 {
00044     fnet_mac_addr_t mac_addr;      /**< @brief ARP cache entry Physical (MAC) address.*/
00045     fnet_ip4_addr_t ip_addr;       /**< @brief ARP cache entry IPv4 address.*/
00046 } fnet_arp_entry_info_t;
00047 FNET_COMP_PACKED_END
00048 
00049 /************************************************************************
00050 *     Function Prototypes
00051 *************************************************************************/
00052 #if defined(__cplusplus)
00053 extern "C" {
00054 #endif
00055 
00056 /***************************************************************************/ /*!
00057  *
00058  * @brief    Retrieves ARP cache entry of the specified network interface.
00059  *
00060  * @param[in] netif_desc  Network interface descriptor.
00061  *
00062  * @param[in] n           Sequence number of ARP cache entry to retrieve (from @c 0).
00063  *
00064  * @param[out] entry_info   Pointer to the ARP cache entry information structure will contain the result.
00065  *
00066  * @return This function returns:
00067  *   - @ref FNET_TRUE if no error occurs and data structure is filled.
00068  *   - @ref FNET_FALSE in case of error or @c n-th entry is not available.
00069  *
00070  ******************************************************************************
00071  *
00072  * This function is used to retrieve ARP cache entries assigned
00073  * the given interface.
00074  *
00075  ******************************************************************************/
00076 fnet_bool_t fnet_arp_get_entry ( fnet_netif_desc_t netif_desc, fnet_index_t n, fnet_arp_entry_info_t *entry_info );
00077 
00078 /***************************************************************************/ /*!
00079  *
00080  * @brief    Gets MAC address of valid ARP cache entry.
00081  *
00082  * @param[in] netif_desc   Network interface descriptor.
00083  *
00084  * @param[in] ip_addr      IPv4 address to search for.
00085  *
00086  * @param[out] mac_addr    Buffer will contain a MAC address corresponding @c ipaddr.@n
00087  *                         This parameter is optional.
00088  *
00089  * @return This function returns:
00090  *   - @ref FNET_TRUE if no error occurs and entry corresponding to @c ip_addr exists.
00091  *   - @ref FNET_FALSE in case of error or entry corresponding to @c ip_addr does not exist.
00092  *
00093  ******************************************************************************
00094  *
00095  * This function searches for an entry corresponding to the provided IPv4 address.@n
00096  * If @c mac_addr parameter is present, it will contain a
00097  * valid MAC address corresponding to @c ip_addr.
00098  *
00099  ******************************************************************************/
00100 fnet_bool_t fnet_arp_get_mac( fnet_netif_desc_t netif_desc, fnet_ip4_addr_t ip_addr, fnet_mac_addr_t mac_addr);
00101 
00102 /***************************************************************************/ /*!
00103  *
00104  * @brief    Sends ARP request.
00105  *
00106  * @param[in] netif_desc  Network interface descriptor.
00107  *
00108  * @param[in] ip_addr      Target protocol address.
00109  *
00110  ******************************************************************************
00111  *
00112  * This function sends a broadcast ARP message, requesting an answer for @c ipaddr.@n
00113  * It can be used for ARP probing of IPv4 address before beginning to use. @n
00114  * Also, it can be used for a gratuitous ARP message when sender's IP address
00115  * or MAC address has changed.
00116  *
00117  ******************************************************************************/
00118 void fnet_arp_send_request( fnet_netif_desc_t netif_desc, fnet_ip4_addr_t ip_addr );
00119 
00120 #if defined(__cplusplus)
00121 }
00122 #endif
00123 
00124 /*! @} */
00125 
00126 #endif  /* FNET_CFG_IP4 */
00127 
00128 #endif /* _FNET_ARP_H_ */