Projects/Plasma/Weather/Ions

    From KDE TechBase
    Revision as of 00:37, 1 August 2008 by Rytilahti (talk | contribs) (Update to follow the current spec, add mentions about WeatherFormula::Unit, add 'list' request)

    Introduction

    This page describes the general naming specification and other information regarding to the Ions. All the data may not be used by the applet(s). If you are going to write an applet or an Ion you should follow this specification to make all parts compatible with each other.

    For providing the weather units use WeatherFormula::Unit so that the applet can easily convert between the units by the user's preference. See plasma/weather/formulas.h for the enum of supported formats, which currently includes the following units:

    • Celsius
    • Fahrenheit
    • Kelvin
    • Kilometers
    • MetersPerSecond
    • Miles
    • Kilopascals
    • InchesHG
    • Millibars
    • Hectopascals
    • Centimeters
    • Millimeters
    • Inches
    • Knots
    • Beaufort

    The conversions between related units can be done between them on the applet's side.

    Applet requests

    The updateIonSource(const QString& source) of the Ion should answer to two requests, validate and weather. In case there is reasonable number of available sources, the ion can provide also list call.

    The format of the request is like this: [name of the ion]|[request]|[parameters]

    When adding the source in the settings dialog of the applet, it will request validation from the Ion. When the Ion has been added, the applet will request for weather information by issuing weather request when it wants to get weather data. See the following chapters for information regarding to these requests.

    Providing a source list

    Ions with reasonable number of sources may want to provide a list of them directly to the user. This can be used in configure dialogs to provide an easy access for them afterwards.

    Request looks always like this: [name of the ion]|list

    Answering to validation request

    <ocde>[name of the ion]|validate|[place name]

    The answers for validate request differ depending the results of the query:

    When the validation is requested, the engine should validate the given place and set the data depending on what happened:

    • When only one valid place for the request is found, the ion should provide

    [ionname]|valid|single|place|[place name] set as the value of validate key of the source.

    • When multiple possible places are found, the ion should provide

    [ionname]|valid|multiple|place|[place name]|place|[place name] set as the value of validate key of the source. The places are separated with '|place|'.

    • When no valid sources are found, the ion should provide

    [ionname]|invalid|single|[place] set as the value of the validate key of the source.

    Answering to the weather information request

    When the weather request is made the Ion should set the appropriate data for the requested source.

    The request looks always like this: [name of the ion]|weather|[place] and the ion should provide the weather data in format which follows the naming scheme found below.

    Naming scheme

    Location data

    Key Value type Description
    Credit string The credit for the data provider
    Country string The country where the weather station is located
    Place string City, territory and perhaps other information where the weather station is located
    Region string Region where the weather station is located
    Station string Name of the station

    Observation data

    Key Value type Description
    Observation Period date How often the weather status is updated
    Current Conditions conditions Current weather conditions

    Temperature fields

    Key Value type Description
    Temperature WeatherFormula::Unit Temperature observed
    Temperature Unit C,F The format of the temperature is in

    Wind data

    Key Value type Description
    Wind Direction string Direction of the wind in degrees or as a cardinal
    Wind Speed int Speed of the wind
    Wind Speed Unit WeatherFormula::Unit The format of the wind speed
    Wind Gust int Wind gust
    Wind Gust Unit WeatherFormula::Unit The format of the wind gust
    Windchill int Wind chill
    Windchill Unit WeatherFormula::Unit The format of the wind chill
    Humidex int Humidex

    Air conditions

    Key Value type Description
    Humidity int Humidity in percents
    Dewpoint int Dewpoint
    Dewpoint Unit WeatherFormula::Unit The format of the dewpoint
    Pressure int Air pressure
    Pressure Unit WeatherFormula::Unit The format of the air pressure
    Pressure Tendency string Tendency of the pressure
    Visibility int Visibility
    Visibility Unit WeatherFormula::Unit Visibility unit

    Sun/moon related data

    Key Value type Description
    Sunrise At time When the sun rises
    Sunset At time When the sunset happens
    Moonrise At time When the moon rises
    Moonset At time When the moonset happens
    UV Index int Ultraviolet index as integer
    UV Rating string Ultraviolet rating in text

    Records related data

    Key Value type Description
    Record High Temperature int The temperature record for the day
    Record Low Temperature int The low temperature record for the day
    Record Rainfall int The rainfall record for the day
    Record Rainfall Unit WeatherFormula::Unit The format of rainfall
    Record Snowfall int The snowfall record for the day
    Record Snowfall Unit WeatherFormula::Unit The format of the snowfall

    Forecast related data

    Key Value type Description
    Long Forecast Day <something?> ? The forecast for up to eight days
    Short Forecast Day <something> ? The forecast for up to five days