path: root/spec/core.context

<?xml version="1.0"?>
<properties xmlns="http://contextkit.freedesktop.org/Provider">
  <doc>
Core Context Properties
=======================

This is the list of the core contextual properties of the Maemo
platform.

This document is maintained as part of the +contextkit+ package.
Please report change requests as bugs against the +contextkit+
package.
 
*NOTE:* Most of these properties are unstable and their definition will
change for some time still.  Only the ones explicitly marked as stable
should be used for now.

Display screens
---------------

These properties talk about the display screens of the device.
  </doc>
  <key name="Screen.TopEdge">
    <type>
      <string-enum>
        <top/>
        <bottom/>
        <left/>
        <right/>
      </string-enum>
    </type>
    <doc>
The edge of the main display screen where the user expects
the top-most UI elements to be.  Possible values are the
strings "top", "bottom", "left", and "right", which refer to
the edges of the screen in its normal orientation as defined
by the graphics hardware.  _(stable)_
    </doc>
  </key>
  <key name="Screen.IsCovered"
       type="bool">
    <doc>
Whether or not the main display screen is covered and can thus not be
seen by the user.  This might mean that the device is laying face down
on a table, or that its lid is closed if it has one.  _(stable)_
    </doc>
  </key>
  <doc>
Location
--------

Best effort location information. If any of the keys are not
appliciable to the current location, they will be unavailable.
  </doc>
  <key name="Location.CurrentSource"
       type="location-source">
    <doc>
      The current source of location information as an enumeration of strings.
    </doc>
  </key>
  <key name="Location.ActiveSources">
    <type>
      <list type="location-source"/>
    </type>
    <doc>
      List of active sources of location information.
    </doc>
  </key>
  <key name="Location.Coordinates">
    <type>
      <list type="number"/>
    </type>
    <doc>
The coordinates of the current position as a list of two or three
doubles.  The first two elemets are latitude and longitude,
respectivly, in degrees.  The third element, when present, is the
altitude in meter.
    </doc>
  </key>
  <key name="Location.Street"
       type="string">
    <doc>The street nearest the location of the device, as a localized string.</doc>
  </key>
  <key name="Location.PostalCode"
       type="string">
    <doc>The postcode of the location of the device, as a localized string.</doc>
  </key>
  <key name="Location.Area"
       type="string">
    <doc>
The name of the local area where the device is, for example a
neighborhood or campus, as a localized string.
    </doc>
  </key>
  <key name="Location.Locality"
       type="string">
    <doc>The name of the village, town or city where the device is, as a localized string.</doc>
  </key>
  <key name="Location.Region"
       type="string">
    <doc>The administrative region which contains the location of the device, as a localized string.</doc>
  </key>
  <key name="Location.Country"
       type="string">
    <doc>The country which contains the location of the device, as a localized string.</doc>
  </key>
  <key name="Location.CountryCode"
       type="string">
    <doc>The ISO 3166 two letter country code of the country which contains the location of the device.</doc>
  </key>
  <key name="Location.Heading"
       type="number">
    <doc>
      The deviation, in degrees (0-360), from the geographical north.
    </doc>
  </key>
  <key name="Location.Timezone"
       type="string">
    <doc>TBD</doc>
  </key>
  <key name="Location.TimezoneOffset"
       type="duration">
    <doc>TBD</doc>
  </key>
  <key name="Location.Continent"
       type="string">
    <doc>The name of the current continent, as a localized string.</doc>
  </key>
  <key name="Location.Planet"
       type="string">
    <doc>The name of the current planet (or dwarf planet), as a localized string.</doc>
  </key>
  <key name="Location.PointOfInterest"
       type="tracker-uri">
    <doc>
The URI of the current point of interest, if any.  (The URI points to
a Tracker object inside the Content Framework.)
    </doc>
  </key>
  <key name="Location.NearbyContacts">
    <type>
      <list type="tracker-uri"/>
    </type>
    <doc>
A list of URIs for contacts that are physically nearby.
    </doc>
  </key>
  <doc>
Position
---------

Information about the physical position of the device.
  </doc>
  <key name="Position.Stable"
       type="bool">
    <doc>
A boolean indicating whether or not the position of the device is
stable, i.e., the device does not move.
    </doc>
  </key>
  <key name="Position.Shaky"
       type="bool">
    <doc>
A boolean indicating whether or not the device is moving rapidly. Not
necessarily the opposite of Position.Stable; both may be false
simultaneously.
    </doc>
  </key>
  <doc>
Battery
-------

Information about the batteries of the device.
  </doc>
  <key name="Battery.ChargePercentage"
       type="percentage">
    <doc>
The average charge level of the currently connected batteries. 
Expressed as percentage of the maximum charge level.
    </doc>
  </key>
  <key name="Battery.OnBattery"
       type="bool">
    <doc>
Whether or not the device is currently running on battery power,
i.e., whether at least one of its batteries is currently discharging.
    </doc>
  </key>
  <key name="Battery.LowBattery"
       type="bool">
    <doc>
Whether or not the device is currently running on low battery power.
True if OnBattery is true and the charge levels of all 
batteries are below 10%.
    </doc>
  </key>
  <key name="Battery.IsCharging"
       type="bool">
    <doc>
Whether or not the device is currently charging at least one of its batteries.
    </doc>
  </key>
  <key name="Battery.TimeUntilLow"
       type="duration">
    <doc>
Estimates the time that the device can run on battery before the property 
OnLowBattery becomes true. In seconds.
    </doc>
  </key>
  <key name="Battery.TimeUntilFull"
       type="duration">
    <doc>
Estimates the needed charging time of the device. In seconds.
    </doc>
  </key>
 <doc>
System
------

Information about the current state of the device.
  </doc>
  <key name="System.MemoryPressure">
    <type>
      <int-enum>
        <normal   value="0"/>
        <high     value="1"/>
        <critical value="2"/>
      </int-enum>
    </type>
    <doc>
Current memory load. Possible values: 0 (normal), 1 (high; low watermark exceeded), 2 (critical; high watermark exceeded).
    </doc>
  </key>
  <doc>
Internet connectivity
---------------------

Information about the connection of the devide to the Internet.
  </doc>
  <key name="Internet.NetworkType">
    <type>
      <string-enum>
        <wifi/>
        <wimax/>
        <cellular/>
        <bluetooth/>
        <ethernet/>
      </string-enum>
    </type>
    <doc>
The type of the current connection to the Internet.  This is one of
the strings "wifi", "wimax", "cellular", "bluetooth", "ethernet", or
"usb".  (From ConnMan.  New types might be defined in the future, of
course.)
    </doc>
  </key>

  <key name="Internet.NetworkName"
       type="string">
    <doc>
      The name of the current network.
    </doc>
  </key>

  <key name="Internet.NetworkState">
    <type>
      <string-enum>
        <disconnected/>
        <connecting/>
        <connected/>
      </string-enum>
    </type>
    <doc>
      The state of the Internet connection, as one of "connected",
      "disconnected", and "connecting".
    </doc>
  </key>
  
  <key name="Internet.SignalStrength"
       type="percentage">
    <doc>
The signal strength of the current connection to the Internet. For
example, when Internet.NetworkType is "cellular", this is the signal
strength at the cellular radio, when it is "wifi", it is the signal
strength at the WLAN radio.
    </doc>
  </key>

  <key name="Internet.TrafficOut"
       type="percentage">
    <doc>
A rough indication of the current traffic rate to the Internet, in
percent of the maximum possible rate.
    </doc>
  </key>
  <key name="Internet.TrafficIn"
       type="percentage">
    <doc>
A rough indication of the current traffic rate from the Internet, in
percent of the maximum possible rate.
    </doc>
  </key>
  <doc>
Bluetooth
---------

Information about Bluetooth related things.      
  </doc>
  <key name="Bluetooth.Enabled"
       type="bool">
    <doc>
A boolean indicating whether or not the Bluetooth radio is enabled.
    </doc>
  </key>
  <key name="Bluetooth.Visible"
       type="bool">
    <doc>
A boolean indicating whether or not the device is visible to other
Bluetooth devices when they search for others.
    </doc>
  </key>
  <doc>
Cellular
--------

Information about the cellular radio.
  </doc>
  <key name="Cellular.NetworkName"
       type="string">
    <doc>
The name of the cellular network.
    </doc>
  </key>
  <key name="Cellular.SignalStrength"
       type="percentage">
    <doc>
The signal strength at the cellular radio, in percent of the maximum.
    </doc>
  </key>
  <key name="Cellular.Technology">
    <type>
      <string-enum>
        <gsm/>
        <umts/>
      </string-enum>
    </type>
    <doc>
The currently used Radio Access Technology.
    </doc>
  </key>
  <key name="Cellular.DataTechnology">
    <type>
      <string-enum>
        <gprs/>
        <egprs/>
        <umts/>
        <hspa/>
      </string-enum>
    </type>
    <doc>
The currently used Radio Access Technology for data transfer.
    </doc>
  </key>
  <key name="Cellular.RegistrationStatus">
    <type>
      <string-enum>
        <home      doc="Registered with the home network"/>
        <roam      doc="Roaming"/>
        <no-sim    doc="No SIM card is present"/>
        <offline   doc="Cellular radio is powered off"/>
        <forbidden doc="Cellular access is denied, e.g., because of invalid SIM"/>
      </string-enum>
    </type>
    <doc>
The current cellular network registration status.
    </doc>
  </key>
  <doc>
User alarms
-----------

Information about the alams set by the user. We assume, that the user
can disable or enable all the alarms. In addition, the user can enable
or disable each alarm individually.
  </doc>
  <key name="UserAlarm.Present"
       type="bool">
    <doc>
Indicates whether there is an upcoming alarm set by the user. Can be
true even if alarms are disabled.
    </doc>
  </key>
  <key name="UserAlarm.Enabled"
       type="bool">
    <doc>
Indicates whether the alarms are enabled or disabled by the user. If
there are no alarms, UserAlarm.Enabled is true.
    </doc>
  </key>
  <key name="UserAlarm.NextTime"
       type="time">
    <doc>
The time of the next (enabled) alarm, in Unix time (the number of
seconds since January 1.1.1970 00:00 UTC). If no alarms are present,
the value is Unknown.
    </doc>
  </key>
  <key name="UserAlarm.NextDescription"
       type="string">
    <doc>
The description of the next (enabled) alarm. If no alarms are present,
the value is Unknown.
    </doc>
  </key>
  <key name="UserAlarm.NextCookie"
       type="integer">
    <doc>
The cookie of the next (enabled) alarm. The cookie can be used for
referring to the alarm when communicating with timed.
    </doc>
  </key>
  <doc>
Environment
-----------

Information about the environment the device is in.
  </doc>
  <key name="Environment.SunRise"
       type="time">
    <doc>
The time of sun rise.
    </doc>
  </key>
  <key name="Environment.SunSet"
       type="time">
    <doc>
The time of sun set.
    </doc>
  </key>
  <key name="Environment.Weather">
    <type>
       <map>
         <Condition type="string">
           <doc>
The current weather condition, as a localized, human readable string.
Examples are "Cloudy", "Raining", etc.
           </doc>
         </Condition>
         <ConditionCode>
           <type>
             <string-enum>
               <cloudy/>
               <sunny/>
             </string-enum>
           </type>
           <doc>
The current weather condition, as a symbolic string.  The set of
symbols is to be defined, but it will be fixed and quite small so that
you can provide an icon for each of them, etc.
           </doc>
         </ConditionCode>
         <Humidity type="percentage">
           <doc>
The relative humidity in percent.
           </doc>
         </Humidity>
         <Temperature type="string">
           <doc>
The temperature as a localized string.  This string represents the
temperature in the way preferred by the user.  Most often this means
either degrees Celsius or degrees Fahrenheit, but it could be some
other unit entirely.
           </doc>
         </Temperature>
         <TemperatureK type="temperature">
           <doc>
The temperature in Kelvin.
           </doc>
         </TemperatureK>
         <ApparentTemperature type="string">
           <doc>
The felt temperature as a localized string, analogous to Temperature.
           </doc>
         </ApparentTemperature>
         <ApparentTemperatureK type="temperature">
           <doc>
The felt temperature in Kelvin.
           </doc>
         </ApparentTemperatureK>
         <DewPoint type="string">
           <doc>
The dew point as a localized string, analogous to Temperature.
           </doc>
         </DewPoint>
         <DewPointK type="temperature">
           <doc>
The dew point in Kelvin.
           </doc>
         </DewPointK>
         <Pressure type="number">
           <doc>
The atmospheric pressure in milli bar.
           </doc>
         </Pressure>
         <Precipitation type="number">
           <doc>
The rain or snow fall in millimeter per square meter per hour (or some
other more common unit).
           </doc>
         </Precipitation>
         <Visibility type="number">
           <doc>
The visibility in meter.
           </doc>
         </Visibility>
         <WindSpeed type="number">
           <doc>
The wind speed in meters per second.
           </doc>
         </WindSpeed>
         <WindDirection type="string">
           <doc>
The wind direction as a localized string.  The direction is given in
compass terms: North, South-West, etc.
           </doc>
         </WindDirection>
         <WindDirectionD type="number">
           <doc>
The wind direction in degrees.  North is 0, east is 90, etc.
           </doc>
         </WindDirectionD>
       </map>
    </type>
    <doc>
The current weather.  See http://www.ominous-valve.com/wx_codes.txt for
more information about codifying weather conditions.  We should lift
something from there, if just for extra geek points.
    </doc>
  </key>
  <key name="Environment.IsDark"
       type="bool">
    <doc>Whether or not it is especially dark.</doc>
  </key>
  <key name="Environment.IsBright"
       type="bool">
    <doc>Whether or not it is especially bright.</doc>
  </key>
  <key name="Environment.IsLoud"
       type="bool">
    <doc>Whether or not it is especially loud.</doc>
  </key>
  <doc>
Use
---

Information about the current usage context of the device.

Situations are a UI concept similar to Profiles that allows the user
to have different customizations for his/her device and
automatically/explcicitly switch between them.  Typical Situations are
"AtHome", "AtWork", "InMeeting" etc.  Some of them are probably
pre-defined, others can be defined by the user.  Situations might form
a hierarchy: InMeeting includes AtWork.

Not much is known about all this right now.
  </doc>
  <key name="Use.Situations"
       type="string-list">
    <doc>
The symbolic names of the currently active Situations.  Note that more
than one situation might be active at the same time.
    </doc>
    </key>
  <key name="Use.Mode">
    <doc>
The current main usage mode of the device.
    </doc>
    <type>
      <string-enum>
	<editing>
          <doc>
The user is interacting closely with the device and is creating new
content, such as when composing a email message or creating any other
kind of document.
          </doc>
	</editing>
	<recording>
          <doc>
The user is taking pictures, or recording video or audio.
          </doc>
	</recording>
	<browsing>
          <doc>
The user is interacting closely with the device without
creating new content, such as when browsing search results, or
browsing through his/her music collection.
          </doc>
	</browsing>
	<watching>
          <doc>
The user is watching a video, without closely interacting with the
device.
          </doc>
	</watching>
	<listening>
          <doc>
The user is listening to audio, without closely interacting with the
device.
          </doc>
	</listening>
        <reading>
          <doc>
The user is reading a document, such as when reading a article on the
web or a e-book.
          </doc>
        </reading>
	<chatting>
          <doc>
The user is involved in a real-time, text-based dialog with external
parties.
          </doc>
	</chatting>
	<gaming>
          <doc>
The user is interacting closely with the device, for entertainment.
          </doc>
	</gaming>
	<calling>
          <doc>
The user is involved in a real-time, audio- or video-based dialog with
external parties.
          </doc>
	</calling>
	<active>
          <doc>
The user interacting closely with the device, for an activity that
doesn't fit into any of the above categories.
          </doc>
	</active>
	<idle>
          <doc>
The device is not being used.
          </doc>
	</idle>
        <maintenance>
          <doc>
The user is doing system-wide maintenance work such as restoring a
backup or upgrading the OS software.
          </doc>
        </maintenance>
      </string-enum>
    </type>
  </key>
  <key name="Use.ConnectedContacts">
    <type>
      <list type="tracker-uri"/>
    </type>
    <doc>
A list of URIs for contacts that the user is currently engaged in
conversations with.  (The URIs point to Tracker objects.)
    </doc>
  </key>    
  <key name="Use.RecentDocuments">
    <type>
      <list type="tracker-uri"/>
    </type>
    <doc>
A list of URIs for recently used documents, at most ten elements long.
(The URIs point to Tracker objects.)
    </doc>
  </key>    
  <key name="Use.Keyboarding"
       type="bool">
    <doc>
Whether or not the user is ready to use the keyboard.  This property
is true when a slideout keyboard has been slided out, for example, or
when a transformer laptop with a tablet mode is in "laptop mode".
    </doc>
  </key>
  <key name="Use.Phoning"
       type="bool">
    <doc>
Whether or not the user is using the device as a telephone handset,
holding it next to ear and mouth.
    </doc>
  </key>
  <doc>
Events
------

Information about current and upcoming calendar entries.
  </doc>
  <key name="Event.Current">
    <type>
      <list type="tracker-uri"/>
    </type>
    <doc>
The currently active events, as a list of Tracker URIs.  The list
contains all events whose start time is earlier than or equal to the
current time, and whose end time is later.
    </doc>
  </key>
  <key name="Event.CurrentStart"
       type="time">
    <doc>
The earliest start time of the events in Events.Current.
    </doc>
  </key>
  <key name="Event.CurrentEnd"
       type="time">
    <doc>
The latest end time of the events in Events.Current.
    </doc>
  </key>
  <key name="Event.Next">
    <type>
      <list type="tracker-uri"/>
    </type>
    <doc>
The upcoming events, as a list of Tracker URIs.  The list contains
those events whose start time is later than the current time and
closest to now.  If there are multiple events in the list, they all
start at exactly the same time.
    </doc>
  </key>
  <key name="Event.NextStart"
       type="time">
    <doc>
The earliest start time of the events in Events.Next.
    </doc>
  </key>
  <key name="Event.NextEnd"
       type="time">
    <doc>
The latest end time of the events in Events.Next.
    </doc>
  </key>
  <doc>
Profiles
--------

Information about the expected behavior of the device.
  </doc>
  <key name="Profile.Name"
       type="string">
    <doc>
The name of the currently active profile as a localized string.  You
should not try to interpret this string, it is only meant to be
displayed as a reminder to the user.
    </doc>
  </key>
  <doc>
Session
-------

Information about the current user session.  If there is no current
session, all values are null.
  </doc>
  <key name="Session.State">
    <type>
      <string-enum>
        <normal/>
        <fullscreen/>
        <blanked/>
      </string-enum>
    </type>
    <doc>
The state of the current session, as string valued enumeration.

The session is in the "normal" state when the normal desktop UI
components such as the panel, desktop icons, taskbars, notification
areas and status menus are available to the user.

The session goes to the "blanked" state when the user stops
interacting with it and the the screen is blanked.  In general, there
is no point in trying to interact with the user when the session is
blanked.

The session is in the "fullscreen" state when the complete screen has
been given to an application, such as full-screen video playback.  In
that state, the notification areas and status menus, etc of the
desktop aren't visible to the user, of course, and notifications
should be unintrusive and important.

Applications should be prepared to see all states in any kind of order
without getting confused.
    </doc>
  </key>
  <doc>
Media
-----

Information about media related activity.
  </doc>
  <key name="Media.NowPlaying">
    <type>
      <map>
        <resource   type="tracker-uri"/>
        <title      type="string"/>
        <artist     type="string"/>
        <genre      type="string"/>
        <album      type="string"/>
        <duration   type="duration"/>
        <start-time type="time"/>
        <state      type="string-enum"/>
      </map>
    </type>
    <doc>
The currently playing media, such as a video or audio track.  The
value is a dictionary with the listed entries.  If "resource" is
included, then "title", "artist", "genre", and "album" are consistent
with what Tracker has stored.

The current position in the media is always "current-time -
start-time".  If the user seeks then that is expressed by changing
"start-time".  In other words, "start-time" is not the point in time
when the user has clicked the play button, it is the point in time
when the media would have had to start to play uninterrupted to reach
its current position now.  This slight complication is done in favor
of transmitting the position directly to avoid telling you once every
second that it is now one second later.
    </doc>
  </key>
</properties>