netapp.h

00001 /*****************************************************************************
00002 *
00003 *  netapp.h  - CC3000 Host Driver Implementation.
00004 *  Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/
00005 *
00006 *  Redistribution and use in source and binary forms, with or without
00007 *  modification, are permitted provided that the following conditions
00008 *  are met:
00009 *
00010 *    Redistributions of source code must retain the above copyright
00011 *    notice, this list of conditions and the following disclaimer.
00012 *
00013 *    Redistributions in binary form must reproduce the above copyright
00014 *    notice, this list of conditions and the following disclaimer in the
00015 *    documentation and/or other materials provided with the   
00016 *    distribution.
00017 *
00018 *    Neither the name of Texas Instruments Incorporated nor the names of
00019 *    its contributors may be used to endorse or promote products derived
00020 *    from this software without specific prior written permission.
00021 *
00022 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00023 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00024 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00026 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00027 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00028 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00029 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00030 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00031 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00032 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 *
00034 *****************************************************************************/
00035 #ifndef __NETAPP_H__
00036 #define    __NETAPP_H__
00037 
00038 
00039 //*****************************************************************************
00040 //
00041 // If building with a C++ compiler, make all of the definitions in this header
00042 // have a C binding.
00043 //
00044 //*****************************************************************************
00045 #ifdef    __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 //*****************************************************************************
00050 //
00051 //! \addtogroup netapp_api
00052 //! @{
00053 //
00054 //*****************************************************************************
00055 
00056 typedef struct _netapp_dhcp_ret_args_t
00057 {
00058     unsigned char aucIP[4];
00059     unsigned char aucSubnetMask[4];
00060     unsigned char aucDefaultGateway[4];
00061     unsigned char aucDHCPServer[4];
00062     unsigned char aucDNSServer[4];
00063 }tNetappDhcpParams;
00064 
00065 typedef struct _netapp_ipconfig_ret_args_t
00066 {
00067     unsigned char aucIP[4];
00068     unsigned char aucSubnetMask[4];
00069     unsigned char aucDefaultGateway[4];
00070     unsigned char aucDHCPServer[4];
00071     unsigned char aucDNSServer[4];
00072     unsigned char uaMacAddr[6];
00073     unsigned char uaSSID[32];
00074 }tNetappIpconfigRetArgs;
00075 
00076 
00077 /*Ping send report parameters*/
00078 typedef struct _netapp_pingreport_args
00079 {
00080     unsigned long packets_sent;
00081     unsigned long packets_received;
00082     unsigned long min_round_time;
00083     unsigned long max_round_time;
00084     unsigned long avg_round_time;
00085 } netapp_pingreport_args_t;
00086 
00087 
00088 //*****************************************************************************
00089 //
00090 //!  netapp_config_mac_adrress
00091 //!
00092 //!  @param  mac   device mac address, 6 bytes. Saved: yes 
00093 //!
00094 //!  @return       return on success 0, otherwise error.
00095 //!
00096 //!  @brief        Configure device MAC address and store it in NVMEM. 
00097 //!                The value of the MAC address configured through the API will
00098 //!                     be stored in CC3000 non volatile memory, thus preserved 
00099 //!                over resets.
00100 //
00101 //*****************************************************************************
00102 extern long  netapp_config_mac_adrress( unsigned char *mac );
00103 
00104 //*****************************************************************************
00105 //
00106 //!  netapp_dhcp
00107 //!
00108 //!  @param  aucIP               device mac address, 6 bytes. Saved: yes 
00109 //!  @param  aucSubnetMask       device mac address, 6 bytes. Saved: yes 
00110 //!  @param  aucDefaultGateway   device mac address, 6 bytes. Saved: yes 
00111 //!  @param  aucDNSServer        device mac address, 6 bytes. Saved: yes 
00112 //!
00113 //!  @return       return on success 0, otherwise error.
00114 //!
00115 //!  @brief       netapp_dhcp is used to configure the network interface, 
00116 //!               static or dynamic (DHCP).\n In order to activate DHCP mode, 
00117 //!               aucIP, aucSubnetMask, aucDefaultGateway must be 0.
00118 //!               The default mode of CC3000 is DHCP mode.
00119 //!               Note that the configuration is saved in non volatile memory
00120 //!               and thus preserved over resets.
00121 //!     
00122 //! @note         If the mode is altered a reset of CC3000 device is required 
00123 //!               in order to apply changes.\nAlso note that asynchronous event 
00124 //!               of DHCP_EVENT, which is generated when an IP address is 
00125 //!               allocated either by the DHCP server or due to static 
00126 //!               allocation is generated only upon a connection to the 
00127 //!               AP was established. 
00128 //!
00129 //*****************************************************************************
00130 extern     long netapp_dhcp(unsigned long *aucIP, unsigned long *aucSubnetMask,unsigned long *aucDefaultGateway, unsigned long *aucDNSServer);
00131 
00132 
00133 
00134 //*****************************************************************************
00135 //
00136 //!  netapp_timeout_values
00137 //!
00138 //!  @param  aucDHCP    DHCP lease time request, also impact 
00139 //!                     the DHCP renew timeout. Range: [0-0xffffffff] seconds,
00140 //!                     0 or 0xffffffff == infinity lease timeout.
00141 //!                     Resolution:10 seconds. Influence: only after 
00142 //!                     reconnecting to the AP. 
00143 //!                     Minimal bound value: MIN_TIMER_VAL_SECONDS - 20 seconds.
00144 //!                     The parameter is saved into the CC3000 NVMEM. 
00145 //!                     The default value on CC3000 is 14400 seconds.
00146 //!     
00147 //!  @param  aucARP     ARP refresh timeout, if ARP entry is not updated by
00148 //!                     incoming packet, the ARP entry will be  deleted by
00149 //!                     the end of the timeout. 
00150 //!                     Range: [0-0xffffffff] seconds, 0 == infinity ARP timeout
00151 //!                     Resolution: 10 seconds. Influence: on runtime.
00152 //!                     Minimal bound value: MIN_TIMER_VAL_SECONDS - 20 seconds
00153 //!                     The parameter is saved into the CC3000 NVMEM. 
00154 //!                        The default value on CC3000 is 3600 seconds.
00155 //!
00156 //!  @param  aucKeepalive   Keepalive event sent by the end of keepalive timeout
00157 //!                         Range: [0-0xffffffff] seconds, 0 == infinity timeout
00158 //!                         Resolution: 10 seconds.
00159 //!                         Influence: on runtime.
00160 //!                         Minimal bound value: MIN_TIMER_VAL_SECONDS - 20 sec
00161 //!                         The parameter is saved into the CC3000 NVMEM. 
00162 //!                         The default value on CC3000 is 10 seconds.
00163 //!
00164 //!  @param  aucInactivity   Socket inactivity timeout, socket timeout is
00165 //!                          refreshed by incoming or outgoing packet, by the
00166 //!                          end of the socket timeout the socket will be closed
00167 //!                          Range: [0-0xffffffff] sec, 0 == infinity timeout.
00168 //!                          Resolution: 10 seconds. Influence: on runtime.
00169 //!                          Minimal bound value: MIN_TIMER_VAL_SECONDS - 20 sec
00170 //!                          The parameter is saved into the CC3000 NVMEM. 
00171 //!                             The default value on CC3000 is 60 seconds.
00172 //!
00173 //!  @return       return on success 0, otherwise error.
00174 //!
00175 //!  @brief       Set new timeout values. Function set new timeout values for: 
00176 //!               DHCP lease timeout, ARP  refresh timeout, keepalive event 
00177 //!               timeout and socket inactivity timeout 
00178 //!     
00179 //! @note         If a parameter set to non zero value which is less than 20s,
00180 //!               it will be set automatically to 20s.
00181 //!
00182 //*****************************************************************************
00183  #ifndef CC3000_TINY_DRIVER
00184 extern long netapp_timeout_values(unsigned long *aucDHCP, unsigned long *aucARP,unsigned long *aucKeepalive,    unsigned long *aucInactivity);
00185 #endif
00186 
00187 //*****************************************************************************
00188 //
00189 //!  netapp_ping_send
00190 //!
00191 //!  @param  ip              destination IP address
00192 //!  @param  pingAttempts    number of echo requests to send
00193 //!  @param  pingSize        send buffer size which may be up to 1400 bytes 
00194 //!  @param  pingTimeout     Time to wait for a response,in milliseconds.
00195 //!
00196 //!  @return       return on success 0, otherwise error.
00197 //!
00198 //!  @brief       send ICMP ECHO_REQUEST to network hosts 
00199 //!     
00200 //! @note         If an operation finished successfully asynchronous ping report 
00201 //!               event will be generated. The report structure is as defined
00202 //!               by structure netapp_pingreport_args_t.
00203 //!
00204 //! @warning      Calling this function while a previous Ping Requests are in 
00205 //!               progress will stop the previous ping request.
00206 //*****************************************************************************
00207 
00208  #ifndef CC3000_TINY_DRIVER
00209 extern long netapp_ping_send(unsigned long *ip, unsigned long ulPingAttempts, unsigned long ulPingSize, unsigned long ulPingTimeout);
00210 #endif
00211 
00212 //*****************************************************************************
00213 //
00214 //!  netapp_ping_stop
00215 //!
00216 //!  @param  none
00217 //!
00218 //!  @return  On success, zero is returned. On error, -1 is returned.      
00219 //!
00220 //!  @brief   Stop any ping request.
00221 //!     
00222 //!
00223 //*****************************************************************************
00224 
00225 #ifndef CC3000_TINY_DRIVER
00226 extern long netapp_ping_stop();
00227 #endif
00228 //*****************************************************************************
00229 //
00230 //!  netapp_ping_report
00231 //!
00232 //!  @param  none
00233 //!
00234 //!  @return  none
00235 //!
00236 //!  @brief   Request for ping status. This API triggers the CC3000 to send 
00237 //!           asynchronous events: HCI_EVNT_WLAN_ASYNC_PING_REPORT.
00238 //!           This event will carry  the report structure:
00239 //!           netapp_pingreport_args_t. This structure is filled in with ping
00240 //!           results up till point of triggering API.
00241 //!           netapp_pingreport_args_t:\n packets_sent - echo sent,
00242 //!           packets_received - echo reply, min_round_time - minimum
00243 //!           round time, max_round_time - max round time,
00244 //!           avg_round_time - average round time
00245 //!     
00246 //! @note     When a ping operation is not active, the returned structure 
00247 //!           fields are 0.
00248 //!
00249 //*****************************************************************************
00250 #ifndef CC3000_TINY_DRIVER
00251 extern void netapp_ping_report();
00252 #endif
00253 
00254 
00255 //*****************************************************************************
00256 //
00257 //!  netapp_ipconfig
00258 //!
00259 //!  @param[out]  ipconfig  This argument is a pointer to a 
00260 //!                         tNetappIpconfigRetArgs structure. This structure is
00261 //!                         filled in with the network interface configuration.
00262 //!                         tNetappIpconfigRetArgs:\n aucIP - ip address,
00263 //!                         aucSubnetMask - mask, aucDefaultGateway - default
00264 //!                         gateway address, aucDHCPServer - dhcp server address
00265 //!                         aucDNSServer - dns server address, uaMacAddr - mac
00266 //!                         address, uaSSID - connected AP ssid
00267 //!
00268 //!  @return  none
00269 //!
00270 //!  @brief   Obtain the CC3000 Network interface information.
00271 //!           Note that the information is available only after the WLAN
00272 //!             connection was established. Calling this function before
00273 //!           associated, will cause non-defined values to be returned.
00274 //!     
00275 //! @note     The function is useful for figuring out the IP Configuration of
00276 //!               the device when DHCP is used and for figuring out the SSID of
00277 //!               the Wireless network the device is associated with.
00278 //!
00279 //*****************************************************************************
00280 
00281 extern void netapp_ipconfig( tNetappIpconfigRetArgs * ipconfig );
00282 
00283 
00284 //*****************************************************************************
00285 //
00286 //!  netapp_arp_flush
00287 //!
00288 //!  @param  none
00289 //!
00290 //!  @return  none
00291 //!
00292 //!  @brief  Flushes ARP table
00293 //!
00294 //*****************************************************************************
00295 
00296 #ifndef CC3000_TINY_DRIVER
00297 extern long netapp_arp_flush();
00298 #endif
00299 
00300 
00301 //*****************************************************************************
00302 //
00303 //!  netapp_set_debug_level
00304 //!
00305 //!  @param[in]      level    debug level. Bitwise [0-8],
00306 //!                         0(disable)or 1(enable).\n Bitwise map: 0 - Critical
00307 //!                         message, 1 information message, 2 - core messages, 3 -
00308 //!                         HCI messages, 4 - Network stack messages, 5 - wlan
00309 //!                         messages, 6 - wlan driver messages, 7 - epprom messages,
00310 //!                         8 - general messages. Default: 0x13f. Saved: no
00311 //!
00312 //!  @return  On success, zero is returned. On error, -1 is returned
00313 //!
00314 //!  @brief   Debug messages sent via the UART debug channel, this function
00315 //!              enable/disable the debug level
00316 //!
00317 //*****************************************************************************
00318 
00319 
00320 #ifndef CC3000_TINY_DRIVER
00321 long netapp_set_debug_level(unsigned long ulLevel);
00322 #endif
00323 //*****************************************************************************
00324 //
00325 // Close the Doxygen group.
00326 //! @}
00327 //
00328 //*****************************************************************************
00329 
00330 
00331 
00332 //*****************************************************************************
00333 //
00334 // Mark the end of the C bindings section for C++ compilers.
00335 //
00336 //*****************************************************************************
00337 #ifdef    __cplusplus
00338 }
00339 #endif // __cplusplus
00340 
00341 #endif    // __NETAPP_H__
00342 
00343