sleekxmpp/plugins/xep_0080/geoloc.py

   1 """
   2     SleekXMPP: The Sleek XMPP Library
   3     Copyright (C) 2010 Nathanael C. Fritz, Erik Reuterborg Larsson
   4     This file is part of SleekXMPP.
   5
   6     See the file LICENSE for copying permission.
   7 """
   8
   9 import logging
  10
  11 import sleekxmpp
  12 from sleekxmpp.plugins.base import BasePlugin
  13 from sleekxmpp.xmlstream import register_stanza_plugin
  14 from sleekxmpp.plugins.xep_0080 import stanza, Geoloc
  15
  16
  17 log = logging.getLogger(__name__)
  18
  19
  20 class XEP_0080(BasePlugin):
  21
  22     """
  23     XEP-0080: User Location
  24     """
  25
  26     name = 'xep_0080'
  27     description = 'XEP-0080: User Location'
  28     dependencies = set(['xep_0163'])
  29     stanza = stanza
  30
  31     def plugin_end(self):
  32         self.xmpp['xep_0163'].remove_interest(Geoloc.namespace)
  33         self.xmpp['xep_0030'].del_feature(feature=Geoloc.namespace)
  34
  35     def session_bind(self, jid):
  36         self.xmpp['xep_0163'].register_pep('user_location', Geoloc)
  37
  38     def publish_location(self, **kwargs):
  39         """
  40         Publish the user's current location.
  41
  42         Arguments:
  43             accuracy    -- Horizontal GPS error in meters.
  44             alt         -- Altitude in meters above or below sea level.
  45             area        -- A named area such as a campus or neighborhood.
  46             bearing     -- GPS bearing (direction in which the entity is
  47                            heading to reach its next waypoint), measured in
  48                            decimal degrees relative to true north.
  49             building    -- A specific building on a street or in an area.
  50             country     -- The nation where the user is located.
  51             countrycode -- The ISO 3166 two-letter country code.
  52             datum       -- GPS datum.
  53             description -- A natural-language name for or description of
  54                            the location.
  55             error       -- Horizontal GPS error in arc minutes. Obsoleted by
  56                            the accuracy parameter.
  57             floor       -- A particular floor in a building.
  58             lat         -- Latitude in decimal degrees North.
  59             locality    -- A locality within the administrative region, such
  60                            as a town or city.
  61             lon         -- Longitude in decimal degrees East.
  62             postalcode  -- A code used for postal delivery.
  63             region      -- An administrative region of the nation, such
  64                            as a state or province.
  65             room        -- A particular room in a building.
  66             speed       -- The speed at which the entity is moving,
  67                            in meters per second.
  68             street      -- A thoroughfare within the locality, or a crossing
  69                            of two thoroughfares.
  70             text        -- A catch-all element that captures any other
  71                            information about the location.
  72             timestamp   -- UTC timestamp specifying the moment when the
  73                            reading was taken.
  74             uri         -- A URI or URL pointing to information about
  75                            the location.
  76
  77             options  -- Optional form of publish options.
  78             ifrom    -- Specify the sender's JID.
  79             block    -- Specify if the send call will block until a response
  80                         is received, or a timeout occurs. Defaults to True.
  81             timeout  -- The length of time (in seconds) to wait for a response
  82                         before exiting the send call if blocking is used.
  83                         Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
  84             callback -- Optional reference to a stream handler function. Will
  85                         be executed when a reply stanza is received.
  86         """
  87         options = kwargs.get('options', None)
  88         ifrom = kwargs.get('ifrom', None)
  89         block = kwargs.get('block', None)
  90         callback = kwargs.get('callback', None)
  91         timeout = kwargs.get('timeout', None)
  92         for param in ('ifrom', 'block', 'callback', 'timeout', 'options'):
  93             if param in kwargs:
  94                 del kwargs[param]
  95
  96         geoloc = Geoloc()
  97         geoloc.values = kwargs
  98
  99         return self.xmpp['xep_0163'].publish(geoloc,
 100                 options=options,
 101                 ifrom=ifrom,
 102                 block=block,
 103                 callback=callback,
 104                 timeout=timeout)
 105
 106     def stop(self, ifrom=None, block=True, callback=None, timeout=None):
 107         """
 108         Clear existing user location information to stop notifications.
 109
 110         Arguments:
 111             ifrom    -- Specify the sender's JID.
 112             block    -- Specify if the send call will block until a response
 113                         is received, or a timeout occurs. Defaults to True.
 114             timeout  -- The length of time (in seconds) to wait for a response
 115                         before exiting the send call if blocking is used.
 116                         Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
 117             callback -- Optional reference to a stream handler function. Will
 118                         be executed when a reply stanza is received.
 119         """
 120         geoloc = Geoloc()
 121         return self.xmpp['xep_0163'].publish(geoloc,
 122                 ifrom=ifrom,
 123                 block=block,
 124                 callback=callback,
 125                 timeout=timeout)