weather

## weather weather |

## Synopsis

                        WeatherLocation;
    WeatherLocation *   weather_location_new                (const gchar *trans_name,
                                                             const gchar *code,
                                                             const gchar *zone,
                                                             const gchar *radar,
                                                             const gchar *coordinates,
                                                             const gchar *country_code,
                                                             const gchar *tz_hint);
    WeatherLocation *   weather_location_clone              (const WeatherLocation *location);
    void                weather_location_free               (WeatherLocation *location);
    gboolean            weather_location_equal              (const WeatherLocation *location1,
                                                             const WeatherLocation *location2);
    enum                WeatherForecastType;
    enum                TempUnit;
    enum                SpeedUnit;
    enum                PressureUnit;
    enum                DistanceUnit;
                        WeatherPrefs;
                        WeatherInfo;
    void                (*WeatherInfoFunc)                  (WeatherInfo *info,
                                                             gpointer data);
    #define             weather_info_new                    (location,
                                                             prefs,
                                                             cb,
                                                             data)
    #define             weather_info_update                 (info,
                                                             prefs,
                                                             cb,
                                                             data)
    void                weather_info_abort                  (WeatherInfo *info);
    WeatherInfo *       weather_info_clone                  (const WeatherInfo *info);
    void                weather_info_free                   (WeatherInfo *info);
    gboolean            weather_info_is_valid               (WeatherInfo *info);
    gboolean            weather_info_network_error          (WeatherInfo *info);
    void                weather_info_to_metric              (WeatherInfo *info);
    void                weather_info_to_imperial            (WeatherInfo *info);
    const WeatherLocation * weather_info_get_location       (WeatherInfo *info);
    const gchar *       weather_info_get_location_name      (WeatherInfo *info);
    const gchar *       weather_info_get_update             (WeatherInfo *info);
    const gchar *       weather_info_get_sky                (WeatherInfo *info);
    const gchar *       weather_info_get_conditions         (WeatherInfo *info);
    const gchar *       weather_info_get_temp               (WeatherInfo *info);
    const gchar *       weather_info_get_temp_min           (WeatherInfo *info);
    const gchar *       weather_info_get_temp_max           (WeatherInfo *info);
    const gchar *       weather_info_get_dew                (WeatherInfo *info);
    const gchar *       weather_info_get_humidity           (WeatherInfo *info);
    const gchar *       weather_info_get_wind               (WeatherInfo *info);
    const gchar *       weather_info_get_pressure           (WeatherInfo *info);
    const gchar *       weather_info_get_visibility         (WeatherInfo *info);
    const gchar *       weather_info_get_apparent           (WeatherInfo *info);
    const gchar *       weather_info_get_sunrise            (WeatherInfo *info);
    const gchar *       weather_info_get_sunset             (WeatherInfo *info);
    const gchar *       weather_info_get_forecast           (WeatherInfo *info);
    GSList *            weather_info_get_forecast_list      (WeatherInfo *info);
    GdkPixbufAnimation * weather_info_get_radar             (WeatherInfo *info);
    const gchar *       weather_info_get_temp_summary       (WeatherInfo *info);
    gchar *             weather_info_get_weather_summary    (WeatherInfo *info);
    const gchar *       weather_info_get_icon_name          (WeatherInfo *info);
    gint                weather_info_next_sun_event         (WeatherInfo *info);
    enum                WeatherWindDirection;
    enum                WeatherSky;
    enum                WeatherConditionPhenomenon;
    enum                WeatherConditionQualifier;
    typedef             WeatherMoonPhase;
    typedef             WeatherMoonLatitude;
    gboolean            weather_info_get_value_update       (WeatherInfo *info,
                                                             time_t *value);
    gboolean            weather_info_get_value_sky          (WeatherInfo *info,
                                                             WeatherSky *sky);
    gboolean            weather_info_get_value_conditions   (WeatherInfo *info,
                                                             WeatherConditionPhenomenon *phenomenon,
                                                             WeatherConditionQualifier *qualifier);
    gboolean            weather_info_get_value_temp         (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_temp_min     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_temp_max     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_dew          (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_apparent     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_wind         (WeatherInfo *info,
                                                             SpeedUnit unit,
                                                             gdouble *speed,
                                                             WeatherWindDirection *direction);
    gboolean            weather_info_get_value_pressure     (WeatherInfo *info,
                                                             PressureUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_visibility   (WeatherInfo *info,
                                                             DistanceUnit unit,
                                                             gdouble *value);
    gboolean            weather_info_get_value_sunrise      (WeatherInfo *info,
                                                             time_t *value);
    gboolean            weather_info_get_value_sunset       (WeatherInfo *info,
                                                             time_t *value);
    gboolean            weather_info_get_value_moonphase    (WeatherInfo *info,
                                                             WeatherMoonPhase *value,
                                                             WeatherMoonLatitude *lat);
    gboolean            weather_info_get_upcoming_moonphases
                                                            (WeatherInfo *info,
                                                             time_t *phases);

## Description

## Details

### WeatherLocation

    typedef struct {
        gchar *name;
        gchar *code;
        gchar *zone;
        gchar *radar;
        gboolean zone_valid;
        gchar *coordinates;
        gdouble  latitude;
        gdouble  longitude;
        gboolean latlon_valid;
        gchar *country_code;
        gchar *tz_hint;
    } WeatherLocation;

### weather_location_new ()

    WeatherLocation *   weather_location_new                (const gchar *trans_name,
                                                             const gchar *code,
                                                             const gchar *zone,
                                                             const gchar *radar,
                                                             const gchar *coordinates,
                                                             const gchar *country_code,
                                                             const gchar *tz_hint);

### weather_location_clone ()

    WeatherLocation *   weather_location_clone              (const WeatherLocation *location);

### weather_location_free ()

    void                weather_location_free               (WeatherLocation *location);

### weather_location_equal ()

    gboolean            weather_location_equal              (const WeatherLocation *location1,
                                                             const WeatherLocation *location2);

### enum WeatherForecastType

    typedef enum {
        FORECAST_STATE,
        FORECAST_ZONE,
        FORECAST_LIST
    } WeatherForecastType;

### enum TempUnit

    typedef enum {
        TEMP_UNIT_INVALID = 0,
        TEMP_UNIT_DEFAULT,
        TEMP_UNIT_KELVIN,
        TEMP_UNIT_CENTIGRADE,
        TEMP_UNIT_FAHRENHEIT
    } TempUnit;

### enum SpeedUnit

    typedef enum {
        SPEED_UNIT_INVALID = 0,
        SPEED_UNIT_DEFAULT,
        SPEED_UNIT_MS,    /* metres per second */
        SPEED_UNIT_KPH,   /* kilometres per hour */
        SPEED_UNIT_MPH,   /* miles per hour */
        SPEED_UNIT_KNOTS, /* Knots */
        SPEED_UNIT_BFT    /* Beaufort scale */
    } SpeedUnit;

### enum PressureUnit

    typedef enum {
        PRESSURE_UNIT_INVALID = 0,
        PRESSURE_UNIT_DEFAULT,
        PRESSURE_UNIT_KPA,    /* kiloPascal */
        PRESSURE_UNIT_HPA,    /* hectoPascal */
        PRESSURE_UNIT_MB,     /* 1 millibars = 1 hectoPascal */
        PRESSURE_UNIT_MM_HG,  /* millimeters of mecury */
        PRESSURE_UNIT_INCH_HG, /* inches of mercury */
        PRESSURE_UNIT_ATM     /* atmosphere */
    } PressureUnit;

### enum DistanceUnit

    typedef enum {
        DISTANCE_UNIT_INVALID = 0,
        DISTANCE_UNIT_DEFAULT,
        DISTANCE_UNIT_METERS,
        DISTANCE_UNIT_KM,
        DISTANCE_UNIT_MILES
    } DistanceUnit;

### WeatherPrefs

    typedef struct {
        WeatherForecastType type;

        gboolean radar;
        const char *radar_custom_url;

        TempUnit temperature_unit;
        SpeedUnit speed_unit;
        PressureUnit pressure_unit;
        DistanceUnit distance_unit;
    } WeatherPrefs;

### WeatherInfo

    typedef struct _WeatherInfo WeatherInfo;

### WeatherInfoFunc ()

    void                (*WeatherInfoFunc)                  (WeatherInfo *info,
                                                             gpointer data);

### weather_info_new()

    #define weather_info_new(location, prefs, cb, data) _weather_info_fill (NULL, (location), (prefs), (cb), (data))

### weather_info_update()

    #define weather_info_update(info, prefs, cb, data) _weather_info_fill ((info), NULL, (prefs), (cb), (data))

### weather_info_abort ()

    void                weather_info_abort                  (WeatherInfo *info);

### weather_info_clone ()

    WeatherInfo *       weather_info_clone                  (const WeatherInfo *info);

### weather_info_free ()

    void                weather_info_free                   (WeatherInfo *info);

### weather_info_is_valid ()

    gboolean            weather_info_is_valid               (WeatherInfo *info);

### weather_info_network_error ()

    gboolean            weather_info_network_error          (WeatherInfo *info);

### weather_info_to_metric ()

    void                weather_info_to_metric              (WeatherInfo *info);

### weather_info_to_imperial ()

    void                weather_info_to_imperial            (WeatherInfo *info);

### weather_info_get_location ()

    const WeatherLocation * weather_info_get_location       (WeatherInfo *info);

### weather_info_get_location_name ()

    const gchar *       weather_info_get_location_name      (WeatherInfo *info);

### weather_info_get_update ()

    const gchar *       weather_info_get_update             (WeatherInfo *info);

### weather_info_get_sky ()

    const gchar *       weather_info_get_sky                (WeatherInfo *info);

### weather_info_get_conditions ()

    const gchar *       weather_info_get_conditions         (WeatherInfo *info);

### weather_info_get_temp ()

    const gchar *       weather_info_get_temp               (WeatherInfo *info);

### weather_info_get_temp_min ()

    const gchar *       weather_info_get_temp_min           (WeatherInfo *info);

### weather_info_get_temp_max ()

    const gchar *       weather_info_get_temp_max           (WeatherInfo *info);

### weather_info_get_dew ()

    const gchar *       weather_info_get_dew                (WeatherInfo *info);

### weather_info_get_humidity ()

    const gchar *       weather_info_get_humidity           (WeatherInfo *info);

### weather_info_get_wind ()

    const gchar *       weather_info_get_wind               (WeatherInfo *info);

### weather_info_get_pressure ()

    const gchar *       weather_info_get_pressure           (WeatherInfo *info);

### weather_info_get_visibility ()

    const gchar *       weather_info_get_visibility         (WeatherInfo *info);

### weather_info_get_apparent ()

    const gchar *       weather_info_get_apparent           (WeatherInfo *info);

### weather_info_get_sunrise ()

    const gchar *       weather_info_get_sunrise            (WeatherInfo *info);

### weather_info_get_sunset ()

    const gchar *       weather_info_get_sunset             (WeatherInfo *info);

### weather_info_get_forecast ()

    const gchar *       weather_info_get_forecast           (WeatherInfo *info);

### weather_info_get_forecast_list ()

    GSList *            weather_info_get_forecast_list      (WeatherInfo *info);

### weather_info_get_radar ()

    GdkPixbufAnimation * weather_info_get_radar             (WeatherInfo *info);

### weather_info_get_temp_summary ()

    const gchar *       weather_info_get_temp_summary       (WeatherInfo *info);

### weather_info_get_weather_summary ()

    gchar *             weather_info_get_weather_summary    (WeatherInfo *info);

### weather_info_get_icon_name ()

    const gchar *       weather_info_get_icon_name          (WeatherInfo *info);

### weather_info_next_sun_event ()

    gint                weather_info_next_sun_event         (WeatherInfo *info);

`info` : | WeatherInfo structure
Returns : | the interval, in seconds, until the next "sun event": - local midnight, when rise and set times are recomputed - next sunrise, when icon changes to daytime version - next sunset, when icon changes to nighttime version

### enum WeatherWindDirection

    enum WeatherWindDirection {
        WIND_INVALID = -1,
        WIND_VARIABLE,
        WIND_N, WIND_NNE, WIND_NE, WIND_ENE,
        WIND_E, WIND_ESE, WIND_SE, WIND_SSE,
        WIND_S, WIND_SSW, WIND_SW, WIND_WSW,
        WIND_W, WIND_WNW, WIND_NW, WIND_NNW,
        WIND_LAST
    };

### enum WeatherSky

    enum WeatherSky {
        SKY_INVALID = -1,
        SKY_CLEAR,
        SKY_BROKEN,
        SKY_SCATTERED,
        SKY_FEW,
        SKY_OVERCAST,
        SKY_LAST
    };

### enum WeatherConditionPhenomenon

    enum WeatherConditionPhenomenon {
        PHENOMENON_INVALID = -1,

        PHENOMENON_NONE,

        PHENOMENON_DRIZZLE,
        PHENOMENON_RAIN,
        PHENOMENON_SNOW,
        PHENOMENON_SNOW_GRAINS,
        PHENOMENON_ICE_CRYSTALS,
        PHENOMENON_ICE_PELLETS,
        PHENOMENON_HAIL,
        PHENOMENON_SMALL_HAIL,
        PHENOMENON_UNKNOWN_PRECIPITATION,

        PHENOMENON_MIST,
        PHENOMENON_FOG,
        PHENOMENON_SMOKE,
        PHENOMENON_VOLCANIC_ASH,
        PHENOMENON_SAND,
        PHENOMENON_HAZE,
        PHENOMENON_SPRAY,
        PHENOMENON_DUST,

        PHENOMENON_SQUALL,
        PHENOMENON_SANDSTORM,
        PHENOMENON_DUSTSTORM,
        PHENOMENON_FUNNEL_CLOUD,
        PHENOMENON_TORNADO,
        PHENOMENON_DUST_WHIRLS,

        PHENOMENON_LAST
    };

### enum WeatherConditionQualifier

    enum WeatherConditionQualifier {
        QUALIFIER_INVALID = -1,

        QUALIFIER_NONE,

        QUALIFIER_VICINITY,

        QUALIFIER_LIGHT,
        QUALIFIER_MODERATE,
        QUALIFIER_HEAVY,
        QUALIFIER_SHALLOW,
        QUALIFIER_PATCHES,
        QUALIFIER_PARTIAL,
        QUALIFIER_THUNDERSTORM,
        QUALIFIER_BLOWING,
        QUALIFIER_SHOWERS,
        QUALIFIER_DRIFTING,
        QUALIFIER_FREEZING,

        QUALIFIER_LAST
    };

### WeatherMoonPhase

    typedef gdouble WeatherMoonPhase;

### WeatherMoonLatitude

    typedef gdouble WeatherMoonLatitude;

### weather_info_get_value_update ()

    gboolean            weather_info_get_value_update       (WeatherInfo *info,
                                                             time_t *value);

### weather_info_get_value_sky ()

    gboolean            weather_info_get_value_sky          (WeatherInfo *info,
                                                             WeatherSky *sky);

### weather_info_get_value_conditions ()

    gboolean            weather_info_get_value_conditions   (WeatherInfo *info,
                                                             WeatherConditionPhenomenon *phenomenon,
                                                             WeatherConditionQualifier *qualifier);

### weather_info_get_value_temp ()

    gboolean            weather_info_get_value_temp         (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);

### weather_info_get_value_temp_min ()

    gboolean            weather_info_get_value_temp_min     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);

### weather_info_get_value_temp_max ()

    gboolean            weather_info_get_value_temp_max     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);

### weather_info_get_value_dew ()

    gboolean            weather_info_get_value_dew          (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);

### weather_info_get_value_apparent ()

    gboolean            weather_info_get_value_apparent     (WeatherInfo *info,
                                                             TempUnit unit,
                                                             gdouble *value);

### weather_info_get_value_wind ()

    gboolean            weather_info_get_value_wind         (WeatherInfo *info,
                                                             SpeedUnit unit,
                                                             gdouble *speed,
                                                             WeatherWindDirection *direction);

### weather_info_get_value_pressure ()

    gboolean            weather_info_get_value_pressure     (WeatherInfo *info,
                                                             PressureUnit unit,
                                                             gdouble *value);

### weather_info_get_value_visibility ()

    gboolean            weather_info_get_value_visibility   (WeatherInfo *info,
                                                             DistanceUnit unit,
                                                             gdouble *value);

### weather_info_get_value_sunrise ()

    gboolean            weather_info_get_value_sunrise      (WeatherInfo *info,
                                                             time_t *value);

### weather_info_get_value_sunset ()

    gboolean            weather_info_get_value_sunset       (WeatherInfo *info,
                                                             time_t *value);

### weather_info_get_value_moonphase ()

    gboolean            weather_info_get_value_moonphase    (WeatherInfo *info,
                                                             WeatherMoonPhase *value,
                                                             WeatherMoonLatitude *lat);

### weather_info_get_upcoming_moonphases ()

    gboolean            weather_info_get_upcoming_moonphases
                                                            (WeatherInfo *info,
                                                             time_t *phases);

`info` : | WeatherInfo containing the time_t of interest
`phases` : | An array of four time_t values that will hold the returned values. The values are estimates of the time of the next new, quarter, full and three-quarter moons.
Returns : | gboolean indicating success or failure