Diff: NWSWeather.h

Revision:

0:4435c965d95d

Child:

1:e077d6502c94

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/NWSWeather.h	Sun Mar 16 15:37:16 2014 +0000
@@ -0,0 +1,211 @@
+
+#ifndef NWSWEATHER_H
+#define NWSWEATHER_H
+#include "mbed.h"
+#include "HTTPClient.h"
+
+/// Return code interpretation.
+typedef enum
+{
+    noerror,        ///< no error, or parameter has been updated.
+    nomemory,       ///< insufficient memory to complete operation.
+    noresponse,     ///< no response from server.
+    badparameter,   ///< bad parameter to function (typically out of range value).
+    noupdate,       ///< no update available.
+    noparamfound    ///< no parameter found.
+} NWSReturnCode_T;
+
+typedef enum
+{
+    isFloat,
+    isInt,
+    isString
+} TypeOf_T;
+
+typedef union
+{
+    float  fValue;      // ValueType 0
+    int    iValue;      // ValueType 1
+    char * sValue;      // ValueType 2
+} Value_T;
+
+typedef struct 
+{
+    char * name;
+    TypeOf_T typeis;
+    bool updated;
+    Value_T value;
+} XMLItem_T;
+
+
+/// NOAA's National Weather Service handler class.
+///
+/// This class will fetch and parse weather data from an XML feed
+/// using a URL such as "http://www.weather.gov/data/current_obs/KALO.xml".
+///
+/// Only the essential parameters are gathered, which is generally those
+/// from which you can derive others. It turns out this is also most of the
+/// parameters.
+/// \li observation_time_rfc822
+/// \li        suggested_pickup
+/// \li suggested_pickup_period
+/// \li                location
+/// \li                 weather
+/// \li                  temp_f
+/// \li                  temp_c
+/// \li       relative_humidity
+/// \li            wind_degrees
+/// \li                wind_mph
+/// \li             pressure_mb
+/// \li             pressure_in
+/// \li              dewpoint_f
+/// \li              dewpoint_c
+/// \li             windchill_f
+/// \li             windchill_c
+/// \li           visibility_mi
+/// \li           icon_url_base
+/// \li           icon_url_name
+/// \li                latitude
+/// \li               longitude
+///
+class NWSWeather
+{
+public:
+
+    /// Constructor.
+    ///
+    /// Create the object to acquire the weather information from NOAA.
+    /// The full form of a valid url to acquire the data from is:
+    /// "http://www.weather.gov/data/current_obs/SITE.xml", where SITE
+    /// is replaced by the proper site location code.
+    ///
+    /// location codes are available at http://weather.noaa.gov/data/nsd_bbsss.txt,
+    /// and you can use the http://forecast.weather.gov/zipcity.php search tool
+    /// to search based on either zip code or city, state.
+    ///
+    /// It is possible to construct the NWSWeather object with an alternate
+    /// base url, but this is only useful if the alternate site is xml
+    /// compatible.
+    ///
+    /// @code
+    /// NWSWeather wx;
+    /// wx.get("KALO"};
+    /// wx.PrintAllWeatherRecords();
+    /// @endcode
+    ///
+    /// @code
+    /// NWSWeather wx("http://some.alternate.site/path/");
+    /// wx.get("KALO"};
+    /// wx.PrintAllWeatherRecords();
+    /// @endcode
+    /// 
+    /// @param baseurl is an optional parameter to set the base url. If this
+    ///     is not set "http://www.weather.gov/data/current_obs/" is used.
+    ///     If it is set, that alternate base url is used.
+    ///
+    NWSWeather(const char * baseurl = "http://www.weather.gov/data/current_obs/");
+    
+    /// Destructor.
+    ~NWSWeather();
+    
+    /// set an alternate base url after construction of the NWSWeather object.
+    ///
+    /// @param alternateurl is the new url to replace the baseurl.
+    /// @param returns success/failure code. @see NWSReturnCode_T.
+    ///
+    NWSReturnCode_T setAlternateURL(const char * alternateurl);
+    
+    /// get the weather data from the specified site.
+    ///
+    /// This does the work to fetch the weather data from the specified site,
+    /// using the baseurl established when the NWSWeather object is constructed.
+    ///
+    /// @param site is the site/location code of the site of interest.
+    /// @param responseSize sets the size of a temporarily allocated buffer
+    ///         into which the data is received.
+    /// @param returns success/failure code. @see NWSReturnCode_T.
+    ///
+    NWSReturnCode_T get(const char * site, int responseSize = 3000);
+    
+    /// get the count of the number of weather parameters.
+    ///
+    /// @returns the count of the number of parameters for which 
+    ///     data is expected.
+    uint16_t count(void);
+
+    /// determines if a specific parameter was updated from the last
+    /// acquisition.
+    ///
+    /// @param i is the item of interest.
+    /// @param returns noerror if the parameter is up to date. @see NWSReturnCode_T.
+    ///
+    NWSReturnCode_T isUpdated(uint16_t i);
+    
+    /// get one of the weather parameters.
+    ///
+    /// @code
+    /// // Iterate over each of the parameters
+    /// for (i=0; i<wx.count(); i++) {
+    ///     char * name; TypeOf_T type; char * value;
+    ///     if (wx.getParam(i, name, &type, value)) {
+    ///         // print the values
+    ///     }
+    /// }
+    /// @endcode
+    ///
+    /// @code
+    /// // Get the names of the available parameters.
+    /// for (i=0; i<wx.count(); i++) {
+    ///     char * name;
+    ///     if (wx.getParam(i, name)) {
+    ///         // print the names of the parameters
+    ///     }
+    /// }
+    /// @endcode
+    ///
+    /// @param i is index of the parameter of interest.
+    /// @param name is a pointer that is set to point to the name of parameter i.
+    /// @param value is an optional pointer that is then set to point to the value of parameter i.
+    /// @param typeis is an optional pointer that is set to indicate the type of the value.
+    /// @param returns success/failure code. @see NWSReturnCode_T.
+    ///
+    NWSReturnCode_T getParam(uint16_t i, char * name, Value_T *value = NULL, TypeOf_T *typeis = NULL);
+    
+    /// get one of the weather parameters.
+    ///
+    /// @code
+    /// TypeOf_T type; char * value;
+    /// if (wx.getParam("temp_f", &type, value)) {
+    ///     // print the values
+    /// }
+    /// @endcode
+    ///
+    /// @param name is a const pointer to a string naming the parameter of interest.
+    /// @param value is a pointer that is set to point to the value of parameter i.
+    /// @param typeis is a pointer that is set to indicate the type of the value.
+    /// @param returns success/failure code. @see NWSReturnCode_T.
+    ///
+    NWSReturnCode_T getParam(const char *name, Value_T *value, TypeOf_T *typeis = NULL);
+    
+    /// Print to stdout the specified weather record.
+    ///
+    /// Prints the specified record as a "Parmeter = value\r\n" string.
+    ///
+    /// @param i specifies the record.
+    ///
+    void PrintWeatherRecord(uint16_t i);
+
+    /// Printa all the records to stdout.
+    ///
+    /// calls PrintWeatherRecord for each parameter.
+    ///
+    void PrintAllWeatherRecords(void);
+    
+private:
+    HTTPClient http;
+    char * m_baseurl;
+    NWSReturnCode_T ParseWeatherRecord(char * p);
+    void ParseWeatherXML(char * message);
+    void ClearWeatherRecords(void);
+};
+#endif // NWSWEATHER_H
\ No newline at end of file