GWeatherInfo: libgweather Reference Manual

GWeatherInfo

Functions

GWeatherInfo *	gweather_info_new ()
void	gweather_info_update ()
void	gweather_info_abort ()
gboolean	gweather_info_is_valid ()
gboolean	gweather_info_network_error ()
void	gweather_info_store_cache ()
const GWeatherLocation *	gweather_info_get_location ()
void	gweather_info_set_location ()
gchar *	gweather_info_get_forecast ()
GSList *	gweather_info_get_forecast_list ()
GWeatherProvider	gweather_info_get_enabled_providers ()
void	gweather_info_set_enabled_providers ()
const gchar *	gweather_info_get_attribution ()
gchar *	gweather_info_get_location_name ()
const gchar *	gweather_info_get_icon_name ()
const gchar *	gweather_info_get_symbolic_icon_name ()
gchar *	gweather_info_get_weather_summary ()
gchar *	gweather_info_get_temp_summary ()
gchar *	gweather_info_get_update ()
gchar *	gweather_info_get_sky ()
gchar *	gweather_info_get_conditions ()
gchar *	gweather_info_get_temp ()
gchar *	gweather_info_get_temp_min ()
gchar *	gweather_info_get_temp_max ()
gchar *	gweather_info_get_dew ()
gchar *	gweather_info_get_humidity ()
gchar *	gweather_info_get_wind ()
gchar *	gweather_info_get_pressure ()
gchar *	gweather_info_get_visibility ()
gchar *	gweather_info_get_apparent ()
gchar *	gweather_info_get_sunrise ()
gchar *	gweather_info_get_sunset ()
GdkPixbufAnimation *	gweather_info_get_radar ()
const gchar *	gweather_conditions_to_string ()
const gchar *	gweather_sky_to_string ()
const gchar *	gweather_wind_direction_to_string ()
gboolean	gweather_info_get_value_update ()
gboolean	gweather_info_get_value_sky ()
gboolean	gweather_info_get_value_conditions ()
gboolean	gweather_info_get_value_temp ()
gboolean	gweather_info_get_value_temp_min ()
gboolean	gweather_info_get_value_temp_max ()
gboolean	gweather_info_get_value_dew ()
gboolean	gweather_info_get_value_apparent ()
gboolean	gweather_info_get_value_wind ()
gboolean	gweather_info_get_value_pressure ()
gboolean	gweather_info_get_value_visibility ()
gboolean	gweather_info_get_value_sunrise ()
gboolean	gweather_info_get_value_sunset ()
gint	gweather_info_next_sun_event ()
gboolean	gweather_info_get_value_moonphase ()
gboolean	gweather_info_get_upcoming_moonphases ()
gboolean	gweather_info_is_daytime ()

Properties

GWeatherProvider	enabled-providers	Read / Write
GWeatherLocation *	location	Read / Write / Construct

Signals

void

updated

Run First

Types and Values

enum	GWeatherProvider
enum	GWeatherConditionPhenomenon
enum	GWeatherConditionQualifier
struct	GWeatherConditions
enum	GWeatherSky
enum	GWeatherWindDirection
typedef	GWeatherMoonLatitude
typedef	GWeatherMoonPhase
enum	GWeatherDistanceUnit
enum	GWeatherPressureUnit
enum	GWeatherSpeedUnit
enum	GWeatherTemperatureUnit
enum	GWeatherForecastType

Object Hierarchy

    GObject
    ╰── GWeatherInfo

Includes

#include <libgweather/gweather.h>

Description

GWeatherInfo provides a handy way to access weather conditions and forecasts from a GWeatherLocation, aggregating multiple different web services.

It includes also astronomical data such as sunrise times and moon phases.

Functions

gweather_info_new ()

GWeatherInfo *
gweather_info_new (GWeatherLocation *location,
                   GWeatherForecastType type);

Builds a new GWeatherInfo that will provide weather information about location .

Parameters

location	the desidered GWeatherLocation (`NULL` for default).	[allow-none]
type	deprecated and ignored

Returns

a new GWeatherInfo.

[transfer full]

gweather_info_update ()

void
gweather_info_update (GWeatherInfo *info);

Requests a reload of weather conditions and forecast data from enabled network services. This call does no synchronous IO: rather, the result is delivered by emitting the “updated” signal. Note that if no network services are enabled, the signal will not be emitted. See “enabled-providers” for details.

Parameters

info

a GWeatherInfo

gweather_info_abort ()

void
gweather_info_abort (GWeatherInfo *info);

gweather_info_is_valid ()

gboolean
gweather_info_is_valid (GWeatherInfo *info);

gweather_info_network_error ()

gboolean
gweather_info_network_error (GWeatherInfo *info);

gweather_info_store_cache ()

void
gweather_info_store_cache (void);

Ensures that any data cached from the network is stored to disk. Calling this is not necessary, as the cache will be saved when the last reference to a GWeatherInfo will be dropped. On the other hand, it must be called if there is any chance that the application will be closed without unreffing all objects, such as when using a language binding that employs a GC.

gweather_info_get_location ()

const GWeatherLocation *
gweather_info_get_location (GWeatherInfo *info);

gweather_info_set_location ()

void
gweather_info_set_location (GWeatherInfo *info,
                            GWeatherLocation *location);

Changes info to report weather for location . Note that this will clear any forecast or current conditions from info , you must call gweather_info_update() to obtain the new data.

Parameters

info	a GWeatherInfo
location	a location for which weather is desired.	[allow-none]

gweather_info_get_forecast ()

gchar *
gweather_info_get_forecast (GWeatherInfo *info);

gweather_info_get_forecast has been deprecated since version 3.10 and should not be used in newly-written code.

Use gweather_info_get_forecast_list() instead.

Parameters

info

a GWeatherInfo

gweather_info_get_forecast_list ()

GSList *
gweather_info_get_forecast_list (GWeatherInfo *info);

Parameters

info

a GWeatherInfo

Returns

list of GWeatherInfo* objects for the forecast. The list is owned by the 'info' object thus is alive as long as the 'info'. This list is filled only when requested with type FORECAST_LIST and if available for given location. The 'update' property is the date/time when the forecast info is used for.

[transfer none][element-type GWeather.Info]

gweather_info_get_enabled_providers ()

GWeatherProvider
gweather_info_get_enabled_providers (GWeatherInfo *info);

gweather_info_set_enabled_providers ()

void
gweather_info_set_enabled_providers (GWeatherInfo *info,
                                     GWeatherProvider providers);

gweather_info_get_attribution ()

const gchar *
gweather_info_get_attribution (GWeatherInfo *info);

Some weather services require the application showing the data to include an attribution text, possibly including links to the service website. This must be shown prominently toghether with the data.

Parameters

info

a GWeatherInfo

Returns

the required attribution text, in Pango markup form, or NULL if not required.

[transfer none]

gweather_info_get_location_name ()

gchar *
gweather_info_get_location_name (GWeatherInfo *info);

gweather_info_get_icon_name ()

const gchar *
gweather_info_get_icon_name (GWeatherInfo *info);

gweather_info_get_symbolic_icon_name ()

const gchar *
gweather_info_get_symbolic_icon_name (GWeatherInfo *info);

gweather_info_get_weather_summary ()

gchar *
gweather_info_get_weather_summary (GWeatherInfo *info);

Parameters

info

a GWeatherInfo

Returns

a summary for current weather conditions.

[transfer full]

gweather_info_get_temp_summary ()

gchar *
gweather_info_get_temp_summary (GWeatherInfo *info);

gweather_info_get_update ()

gchar *
gweather_info_get_update (GWeatherInfo *info);

gweather_info_get_sky ()

gchar *
gweather_info_get_sky (GWeatherInfo *info);

gweather_info_get_conditions ()

gchar *
gweather_info_get_conditions (GWeatherInfo *info);

gweather_info_get_temp ()

gchar *
gweather_info_get_temp (GWeatherInfo *info);

gweather_info_get_temp_min ()

gchar *
gweather_info_get_temp_min (GWeatherInfo *info);

gweather_info_get_temp_max ()

gchar *
gweather_info_get_temp_max (GWeatherInfo *info);

gweather_info_get_dew ()

gchar *
gweather_info_get_dew (GWeatherInfo *info);

gweather_info_get_humidity ()

gchar *
gweather_info_get_humidity (GWeatherInfo *info);

gweather_info_get_wind ()

gchar *
gweather_info_get_wind (GWeatherInfo *info);

gweather_info_get_pressure ()

gchar *
gweather_info_get_pressure (GWeatherInfo *info);

gweather_info_get_visibility ()

gchar *
gweather_info_get_visibility (GWeatherInfo *info);

gweather_info_get_apparent ()

gchar *
gweather_info_get_apparent (GWeatherInfo *info);

gweather_info_get_sunrise ()

gchar *
gweather_info_get_sunrise (GWeatherInfo *info);

gweather_info_get_sunset ()

gchar *
gweather_info_get_sunset (GWeatherInfo *info);

gweather_info_get_radar ()

GdkPixbufAnimation *
gweather_info_get_radar (GWeatherInfo *info);

Parameters

info

a GWeatherInfo

Returns

what?.

[transfer none]

gweather_conditions_to_string ()

const gchar *
gweather_conditions_to_string (GWeatherConditions *conditions);

gweather_sky_to_string ()

const gchar *
gweather_sky_to_string (GWeatherSky sky);

gweather_wind_direction_to_string ()

const gchar *
gweather_wind_direction_to_string (GWeatherWindDirection wind);

gweather_info_get_value_update ()

gboolean
gweather_info_get_value_update (GWeatherInfo *info,
                                time_t *value);

Parameters

info	a GWeatherInfo
value	the time `info` was last updated.	[out][type glong]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_sky ()

gboolean
gweather_info_get_value_sky (GWeatherInfo *info,
                             GWeatherSky *sky);

Fills out sky with current sky conditions.

Parameters

info	a GWeatherInfo
sky	a location for a GWeatherSky.	[out]

Returns

TRUE is sky is valid, FALSE otherwise.

gweather_info_get_value_conditions ()

gboolean
gweather_info_get_value_conditions (GWeatherInfo *info,
                                    GWeatherConditionPhenomenon *phenomenon,
                                    GWeatherConditionQualifier *qualifier);

Fills out phenomenon and qualifier with current weather conditions.

Parameters

info	a GWeatherInfo
phenomenon	a location for a GWeatherConditionPhenomenon.	[out]
qualifier	a location for a GWeatherConditionQualifier.	[out]

Returns

TRUE is out arguments are valid, FALSE otherwise.

gweather_info_get_value_temp ()

gboolean
gweather_info_get_value_temp (GWeatherInfo *info,
                              GWeatherTemperatureUnit unit,
                              gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherTemperatureUnit
value	the temperature value.	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_temp_min ()

gboolean
gweather_info_get_value_temp_min (GWeatherInfo *info,
                                  GWeatherTemperatureUnit unit,
                                  gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherTemperatureUnit
value	the minimum temperature value.	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_temp_max ()

gboolean
gweather_info_get_value_temp_max (GWeatherInfo *info,
                                  GWeatherTemperatureUnit unit,
                                  gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherTemperatureUnit
value	the maximum temperature value.	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_dew ()

gboolean
gweather_info_get_value_dew (GWeatherInfo *info,
                             GWeatherTemperatureUnit unit,
                             gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherTemperatureUnit
value	the dew point.	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_apparent ()

gboolean
gweather_info_get_value_apparent (GWeatherInfo *info,
                                  GWeatherTemperatureUnit unit,
                                  gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherTemperatureUnit
value	the apparent temperature.	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_wind ()

gboolean
gweather_info_get_value_wind (GWeatherInfo *info,
                              GWeatherSpeedUnit unit,
                              gdouble *speed,
                              GWeatherWindDirection *direction);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherSpeedUnit
speed	forecasted wind speed.	[out]
direction	forecasted wind direction.	[out]

Returns

TRUE if speed and direction are valid, FALSE otherwise.

gweather_info_get_value_pressure ()

gboolean
gweather_info_get_value_pressure (GWeatherInfo *info,
                                  GWeatherPressureUnit unit,
                                  gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherPressureUnit
value	forecasted pressure, expressed in `unit` .	[out]

Returns

TRUE if value is valid, FALSE otherwise.

gweather_info_get_value_visibility ()

gboolean
gweather_info_get_value_visibility (GWeatherInfo *info,
                                    GWeatherDistanceUnit unit,
                                    gdouble *value);

Parameters

info	a GWeatherInfo
unit	the desired unit, as a GWeatherDistanceUnit
value	forecasted visibility, expressed in `unit` .	[out]

Returns

TRUE if value is valid, FALSE otherwise.

gweather_info_get_value_sunrise ()

gboolean
gweather_info_get_value_sunrise (GWeatherInfo *info,
                                 time_t *value);

Parameters

info	a GWeatherInfo
value	the time of sunrise.	[out][type gulong]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_value_sunset ()

gboolean
gweather_info_get_value_sunset (GWeatherInfo *info,
                                time_t *value);

Parameters

info	a GWeatherInfo
value	the time of sunset.	[out][type gulong]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_next_sun_event ()

gint
gweather_info_next_sun_event (GWeatherInfo *info);

gweather_info_get_value_moonphase ()

gboolean
gweather_info_get_value_moonphase (GWeatherInfo *info,
                                   GWeatherMoonPhase *value,
                                   GWeatherMoonLatitude *lat);

Parameters

info	a GWeatherInfo
value	the current moon phase (represented as the visible percentage).	[out]
lat	the latitude the moon is at (???).	[out]

Returns

TRUE is value is valid, FALSE otherwise.

gweather_info_get_upcoming_moonphases ()

gboolean
gweather_info_get_upcoming_moonphases (GWeatherInfo *info,
                                       time_t *phases);

Parameters

info	a GWeatherInfo 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.	[out][array fixed-size=4][element-type gulong]

Returns

gboolean indicating success or failure

gweather_info_is_daytime ()

gboolean
gweather_info_is_daytime (GWeatherInfo *info);

Parameters

info

a GWeatherInfo

Returns

Whether it is daytime (that is, if the sun is visible) or not at the location and the point of time referred by info . This is mostly equivalent to comparing the return value of gweather_info_get_value_sunrise() and gweather_info_get_value_sunset(), but it accounts also for midnight sun and polar night, for locations within the Artic and Antartic circles.

Types and Values

enum GWeatherProvider

Members

GWEATHER_PROVIDER_NONE	no provider, no weather information available
GWEATHER_PROVIDER_METAR	METAR office, providing current conditions worldwide
GWEATHER_PROVIDER_IWIN	US weather office, providing 7 days of forecast
GWEATHER_PROVIDER_YAHOO	Yahoo Weather Service, worldwide but non commercial only
GWEATHER_PROVIDER_YR_NO	Yr.no service, worldwide but requires attribution
GWEATHER_PROVIDER_OWM	OpenWeatherMap, worldwide and possibly more reliable, but requires attribution and is limited in the number of queries
GWEATHER_PROVIDER_ALL	enable all available providers

enum GWeatherConditionPhenomenon

Members

GWEATHER_PHENOMENON_INVALID
GWEATHER_PHENOMENON_NONE
GWEATHER_PHENOMENON_DRIZZLE
GWEATHER_PHENOMENON_RAIN
GWEATHER_PHENOMENON_SNOW
GWEATHER_PHENOMENON_SNOW_GRAINS
GWEATHER_PHENOMENON_ICE_CRYSTALS
GWEATHER_PHENOMENON_ICE_PELLETS
GWEATHER_PHENOMENON_HAIL
GWEATHER_PHENOMENON_SMALL_HAIL
GWEATHER_PHENOMENON_UNKNOWN_PRECIPITATION
GWEATHER_PHENOMENON_MIST
GWEATHER_PHENOMENON_FOG
GWEATHER_PHENOMENON_SMOKE
GWEATHER_PHENOMENON_VOLCANIC_ASH
GWEATHER_PHENOMENON_SAND
GWEATHER_PHENOMENON_HAZE
GWEATHER_PHENOMENON_SPRAY
GWEATHER_PHENOMENON_DUST
GWEATHER_PHENOMENON_SQUALL
GWEATHER_PHENOMENON_SANDSTORM
GWEATHER_PHENOMENON_DUSTSTORM
GWEATHER_PHENOMENON_FUNNEL_CLOUD
GWEATHER_PHENOMENON_TORNADO
GWEATHER_PHENOMENON_DUST_WHIRLS
GWEATHER_PHENOMENON_LAST

enum GWeatherConditionQualifier

Members

GWEATHER_QUALIFIER_INVALID
GWEATHER_QUALIFIER_NONE
GWEATHER_QUALIFIER_VICINITY
GWEATHER_QUALIFIER_LIGHT
GWEATHER_QUALIFIER_MODERATE
GWEATHER_QUALIFIER_HEAVY
GWEATHER_QUALIFIER_SHALLOW
GWEATHER_QUALIFIER_PATCHES
GWEATHER_QUALIFIER_PARTIAL
GWEATHER_QUALIFIER_THUNDERSTORM
GWEATHER_QUALIFIER_BLOWING
GWEATHER_QUALIFIER_SHOWERS
GWEATHER_QUALIFIER_DRIFTING
GWEATHER_QUALIFIER_FREEZING
GWEATHER_QUALIFIER_LAST

struct GWeatherConditions

struct GWeatherConditions {
    gboolean significant;
    GWeatherConditionPhenomenon phenomenon;
    GWeatherConditionQualifier qualifier;
};

enum GWeatherSky

Members

GWEATHER_SKY_INVALID
GWEATHER_SKY_CLEAR
GWEATHER_SKY_BROKEN
GWEATHER_SKY_SCATTERED
GWEATHER_SKY_FEW
GWEATHER_SKY_OVERCAST
GWEATHER_SKY_LAST

enum GWeatherWindDirection

Members

GWEATHER_WIND_INVALID
GWEATHER_WIND_VARIABLE
GWEATHER_WIND_N
GWEATHER_WIND_NNE
GWEATHER_WIND_NE
GWEATHER_WIND_ENE
GWEATHER_WIND_E
GWEATHER_WIND_ESE
GWEATHER_WIND_SE
GWEATHER_WIND_SSE
GWEATHER_WIND_S
GWEATHER_WIND_SSW
GWEATHER_WIND_SW
GWEATHER_WIND_WSW
GWEATHER_WIND_W
GWEATHER_WIND_WNW
GWEATHER_WIND_NW
GWEATHER_WIND_NNW
GWEATHER_WIND_LAST

GWeatherMoonLatitude

typedef gdouble GWeatherMoonLatitude;

GWeatherMoonPhase

typedef gdouble GWeatherMoonPhase;

enum GWeatherDistanceUnit

Members

GWEATHER_DISTANCE_UNIT_INVALID
GWEATHER_DISTANCE_UNIT_DEFAULT
GWEATHER_DISTANCE_UNIT_METERS
GWEATHER_DISTANCE_UNIT_KM
GWEATHER_DISTANCE_UNIT_MILES

enum GWeatherPressureUnit

Members

GWEATHER_PRESSURE_UNIT_INVALID
GWEATHER_PRESSURE_UNIT_DEFAULT
GWEATHER_PRESSURE_UNIT_KPA
GWEATHER_PRESSURE_UNIT_HPA
GWEATHER_PRESSURE_UNIT_MB
GWEATHER_PRESSURE_UNIT_MM_HG
GWEATHER_PRESSURE_UNIT_INCH_HG
GWEATHER_PRESSURE_UNIT_ATM

enum GWeatherSpeedUnit

Members

GWEATHER_SPEED_UNIT_INVALID
GWEATHER_SPEED_UNIT_DEFAULT
GWEATHER_SPEED_UNIT_MS
GWEATHER_SPEED_UNIT_KPH
GWEATHER_SPEED_UNIT_MPH
GWEATHER_SPEED_UNIT_KNOTS
GWEATHER_SPEED_UNIT_BFT

enum GWeatherTemperatureUnit

Members

GWEATHER_TEMP_UNIT_INVALID
GWEATHER_TEMP_UNIT_DEFAULT
GWEATHER_TEMP_UNIT_KELVIN
GWEATHER_TEMP_UNIT_CENTIGRADE
GWEATHER_TEMP_UNIT_FAHRENHEIT

enum GWeatherForecastType

Members

GWEATHER_FORECAST_STATE
GWEATHER_FORECAST_ZONE
GWEATHER_FORECAST_LIST

Property Details

The `“enabled-providers”` property

  “enabled-providers”        GWeatherProvider

A bitmask of enabled weather service providers.

Flags: Read / Write

Default value: GWEATHER_PROVIDER_METAR | GWEATHER_PROVIDER_IWIN

The `“location”` property

  “location”                 GWeatherLocation *

The location this info represents.

Flags: Read / Write / Construct

Signal Details

The `“updated”` signal

void
user_function (GWeatherInfo *object,
               gpointer      user_data)

This signal is emitted after the initial fetch of the weather data from upstream services, and after every successful call to gweather_info_update() .

Parameters

object	the emitter of the signal.
user_data	user data set when the signal handler was connected.

Flags: Run First