cy_nw_helper.h

00001 /*
00002  * Copyright 2019-2021, Cypress Semiconductor Corporation (an Infineon company) or
00003  * an affiliate of Cypress Semiconductor Corporation.  All rights reserved.
00004  *
00005  * This software, including source code, documentation and related
00006  * materials ("Software") is owned by Cypress Semiconductor Corporation
00007  * or one of its affiliates ("Cypress") and is protected by and subject to
00008  * worldwide patent protection (United States and foreign),
00009  * United States copyright laws and international treaty provisions.
00010  * Therefore, you may use this Software only as provided in the license
00011  * agreement accompanying the software package from which you
00012  * obtained this Software ("EULA").
00013  * If no EULA applies, Cypress hereby grants you a personal, non-exclusive,
00014  * non-transferable license to copy, modify, and compile the Software
00015  * source code solely for use in connection with Cypress's
00016  * integrated circuit products.  Any reproduction, modification, translation,
00017  * compilation, or representation of this Software except as specified
00018  * above is prohibited without the express written permission of Cypress.
00019  *
00020  * Disclaimer: THIS SOFTWARE IS PROVIDED AS-IS, WITH NO WARRANTY OF ANY KIND,
00021  * EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, NONINFRINGEMENT, IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress
00023  * reserves the right to make changes to the Software without notice. Cypress
00024  * does not assume any liability arising out of the application or use of the
00025  * Software or any product or circuit described in the Software. Cypress does
00026  * not authorize its products for use in any products where a malfunction or
00027  * failure of the Cypress product may reasonably be expected to result in
00028  * significant property damage, injury or death ("High Risk Product"). By
00029  * including Cypress's product in a High Risk Product, the manufacturer
00030  * of such system or application assumes all risk of such use and in doing
00031  * so agrees to indemnify Cypress against all liability.
00032  */
00033 
00034 /** @file
00035  * 
00036  * This is a collection of network helper functions which would be used by various Cypress Middleware libraries.
00037  * 
00038  */
00039 #pragma once
00040 
00041 #include <stdint.h>
00042 #include <stdbool.h>
00043 
00044 
00045 #if defined(__cplusplus)
00046 extern "C" {
00047 #endif
00048 
00049 /** \addtogroup nwhelper_utils 
00050  * This is a collection of network helper functions to fetch IPv4 address of the local device, notify IPv4 address 
00051  * change via callback and conversion utilities.
00052  */
00053 
00054 #define cy_assert( error_string, assertion )         do { (void)(assertion); } while(0)
00055 
00056 typedef uintptr_t cy_nw_ip_interface_t;
00057 
00058 
00059 /******************************************************
00060  *                   Enumerations
00061  ******************************************************/
00062 /******************************************************************************/
00063 /** \addtogroup group_nwhelper_enums 
00064  * This provides the documentation of all the enums provided by this utility.
00065  *//** \{ */
00066 /******************************************************************************/
00067 /** IP version */
00068 typedef enum nw_ip_version
00069 {
00070     NW_IP_IPV4 = 4,          /**< IPv4 version */
00071     NW_IP_IPV6 = 6,          /**< IPv6 version */
00072     NW_IP_INVALID_IP = (-1), /**< Invalid IP version */
00073 } cy_nw_ip_version_t;
00074 
00075 /** Network interface type */
00076 typedef enum
00077 {
00078     CY_NW_INF_TYPE_WIFI = 0, /**< Wi-Fi network interface */
00079     CY_NW_INF_TYPE_ETH       /**< Ethernet network interface */
00080 } cy_network_interface_type_t;
00081 
00082 /** \} */
00083 
00084 /******************************************************************************/
00085 /** \addtogroup group_nwhelper_structures 
00086  * Lists all the data structures and typedefs provided with the network helper utility along with the documentation.
00087  *//** \{ */
00088 /******************************************************************************/
00089 /** Network IP status change callback function
00090  *
00091  * @param[in] iface : Pointer to the network interface for which the callback is invoked.
00092  * @param[in] arg   : User data object provided during the status change callback registration.
00093 
00094  * @return none
00095  */
00096 typedef void (cy_nw_ip_status_change_callback_func_t)(cy_nw_ip_interface_t iface, void *arg);
00097 
00098 /** Network IP status change callback info */
00099 typedef struct cy_nw_ip_status_change_callback
00100 {
00101     cy_nw_ip_status_change_callback_func_t *cb_func; /**< IP address status change callback function */
00102     void *arg;                                    /**< User data */
00103     void *priv;                                   /**< NW interface */
00104 } cy_nw_ip_status_change_callback_t;
00105 
00106 /**
00107  * IP addr info
00108  */
00109 typedef struct cy_nw_ip_address
00110 {
00111     cy_nw_ip_version_t version; /**< IP version */
00112 
00113     union
00114     {
00115         uint32_t v4;         /**< IPv4 address info */
00116         uint32_t v6[4];      /**< IPv6 address info */
00117     } ip;                    /**< Union of IPv4 and IPv6 address info */
00118 } cy_nw_ip_address_t;
00119 
00120 /** Network interface object */
00121 typedef void* cy_network_interface_object_t;
00122 
00123 /** MAC Address info */
00124 typedef struct cy_nw_ip_mac
00125 {
00126     uint8_t    mac[6];              /**< MAC address                */
00127 } cy_nw_ip_mac_t;
00128 
00129 /** ARP Cache Entry info */
00130 typedef struct cy_nw_arp_cache_entry
00131 {
00132     cy_nw_ip_address_t    ip;         /**< IP address                 */
00133     cy_nw_ip_mac_t        mac;        /**< MAC address                */
00134 } cy_nw_arp_cache_entry_t;
00135 
00136 /**
00137  * Network interface info structure
00138  */
00139 typedef struct
00140 {
00141     cy_network_interface_type_t     type;     /**< Network interface type */
00142     cy_network_interface_object_t   object;   /**< Pointer to the network interface object */
00143 } cy_network_interface_t;
00144 
00145 /** \} */
00146 
00147 /*****************************************************************************/
00148 /**
00149  *
00150  *  @addtogroup group_nwhelper_func
00151  *
00152  * This is a collection of network helper functions which would be used by various Cypress Middleware libraries.
00153  *
00154  *  @{
00155  */
00156 /*****************************************************************************/
00157 
00158 /** Initialize status change callback
00159  *
00160  * Initialize @ref cy_nw_ip_status_change_callback_t instead of
00161  * directly manipulating the callback struct.
00162  *
00163  * @param[in, out] info : Pointer to network IP status change callback information structure which would be filled upon return
00164  * @param[in] cbf       : Pointer to callback function to be invoked during network status change
00165  * @param[in] arg       : User data object to be sent sent in the callback function
00166  *
00167  * @return none
00168  */
00169 void cy_nw_ip_initialize_status_change_callback(cy_nw_ip_status_change_callback_t *info, cy_nw_ip_status_change_callback_func_t *cbf, void *arg);
00170 
00171 /** Retrieves the IPv4 address for an interface
00172  *
00173  * Retrieves the IPv4 address for an interface (AP or STA) if it
00174  * exists.
00175  *
00176  * @param[in]  iface : Pointer to network interface object
00177  * @param[out] addr  : Pointer to the IP information sturcture in which the results to be stored
00178  *
00179  * @return true  : if IP address is present
00180  * @return false : otherwise
00181  */
00182 bool cy_nw_ip_get_ipv4_address(cy_nw_ip_interface_t iface, cy_nw_ip_address_t *addr);
00183 
00184 /** Convert IPv4 string to an IP address structure.
00185  *
00186  * @param[in]  ip_str  :  IPv4 address string.
00187  * @param[out] address :  Pointer to the IP info structure in which the IPv4 address to be stored
00188  *
00189  * @return    0 : if successful
00190  * @return   -1 : if failed
00191  */
00192 int cy_nw_str_to_ipv4(const char *ip_str, cy_nw_ip_address_t *address);
00193 
00194 /** Registers for callback function to be invoked during IP status change
00195  *
00196  * @param[in] iface : Pointer to network interface object
00197  * @param[in] info  : Pointer to the status change information structure
00198  *
00199  * @return none
00200  */
00201 void cy_nw_ip_register_status_change_callback(cy_nw_ip_interface_t iface, cy_nw_ip_status_change_callback_t *info);
00202 
00203 /** Un-registers IP status change callback
00204  *
00205  * @param[in] iface : Pointer to network interface object
00206  * @param[in] info  : Pointer to the status change information structure
00207  *
00208  * @return none
00209  */
00210 void cy_nw_ip_unregister_status_change_callback(cy_nw_ip_interface_t iface, cy_nw_ip_status_change_callback_t *info);
00211 
00212 /** Clears the ARP cache for the interface
00213  * NOTE: in LwIP, we need the netif (NetworkInterface) to do things, we can find using wifi interface.
00214  *
00215  * @param[in] iface : Pointer to network interface object
00216  *
00217  *  @return 0 : success
00218  *          1 : fail
00219  */
00220 int cy_nw_host_arp_cache_clear( cy_nw_ip_interface_t iface );
00221 
00222 /** Gets the ARP cache list for the interface
00223  *
00224  * @param[in]  iface      : Pointer to network interface object
00225  * @param[in, out] list   : Pointer to @ref cy_nw_arp_cache_entry_t array
00226  * @param[in]  count      : Number of entries in the array passed in `list`
00227  * @param[in, out] filled : Pointer to get the number of entries filled in the array pointed by 'list'
00228  *
00229  * @return  0 : success
00230  *          1 : fail
00231  */
00232 int cy_nw_host_arp_cache_get_list( cy_nw_ip_interface_t iface, cy_nw_arp_cache_entry_t *list, uint32_t count, uint32_t *filled );
00233 
00234 /** Send ARP request
00235  * NOTE: in LwIP, we need the netif (NetworkInterface) to do things, we can find using wifi interface.
00236  *
00237  * @param[in]  iface     : Pointer to network interface object
00238  * @param[in]  ip_string : Pointer to the IPv4 address string (Ex: "192.168.1.1") to which the ARP request to be sent
00239  *
00240  * @return 0 : success
00241  *         1 : failed to send ARP request
00242  */
00243 int cy_nw_host_send_arp_request( cy_nw_ip_interface_t iface, const char *ip_string );
00244 
00245 /** GET time in milliseconds
00246  *
00247  * @return time in milliseconds
00248  * */
00249 uint32_t cy_nw_get_time (void);
00250 
00251 /** GET IPv4 address in decimal notation.
00252  *
00253  * NOTE: dotted-decimal notation example (192.168.0.1)
00254  *
00255  * @param[in]  char_ptr : Pointer to the string containing the IPv4 address in dotted-decimal format.
00256  * @param[out] addr     : Pointer to the structure containing IPv4 address in decimal format.
00257  *
00258  * @return 0 : success
00259  *         1 : failed
00260  * */
00261 bool cy_nw_aton (const char *char_ptr , cy_nw_ip_address_t *addr);
00262 
00263 /** GET IPv6 address in decimal notation.
00264  * NOTE: This API does not support shorthand representation of IPv6 address. Input string should be of the format X:X:X:X:X:X:X:X.
00265  *
00266  * @param[in]  char_ptr : Pointer to the string containing the IPv6 address.
00267  * @param[out] addr     : Pointer to the structure containing IPv6 address in decimal format.
00268  *
00269  * @return 0 : success
00270  *         1 : failed
00271  * */
00272 bool cy_nw_aton_ipv6(const char *char_ptr , cy_nw_ip_address_t *addr);
00273 
00274 /** GET IPv4 address in string format.
00275  * 
00276  * @param[in]  addr     : Pointer to IPv4 address structure containing the IPv4 address.
00277  * @param[out] ip_str   : Pointer to the string containing IPv4 address in dotted-decimal notation.
00278  *                        ip_str must be 16 bytes long.
00279  * @return 0 : success
00280  *         1 : failed
00281  * */
00282 bool cy_nw_ntoa (cy_nw_ip_address_t *addr, char *ip_str);
00283 
00284 /** GET IPv6 address in string format.
00285  *
00286  * @param[in]  addr     : Pointer to IPv6 address structure containing the IPv6 address.
00287  * @param[out] ip_str   : Pointer to the string containing IPv6 address.
00288  *                        ip_str must 39 bytes long.
00289  * @return 0 : success
00290  *         1 : failed
00291  * */
00292 bool cy_nw_ntoa_ipv6 (cy_nw_ip_address_t *addr, char *ip_str);
00293 
00294 /** @} */
00295 
00296 #if defined(__cplusplus)
00297 }
00298 #endif