geoclue

README

Go-Geoclue2

Go D-Bus bindings for Geoclue2

Tested with Geoclue 2 - Version 2.5.6 and Go 1.13

Additional information: Geoclue2 D-Bus Specs

Usage

You can find some examples in the examples directory.

Notes

Agent interface not implement/tested.

A Go-ModemManager Dbus Wrapper can be found here.

License

• MIT license
• Copyright 2020 © Malte Grosse.

Documentation

Index

• Constants
• type GClueAccuracyLevel
  • func (i GClueAccuracyLevel) String() string
• type GeoclueAgent
  • func NewGeoclueAgent() (GeoclueAgent, error)
• type GeoclueClient
  • func NewGeoclueClient(objectPath dbus.ObjectPath) (GeoclueClient, error)
• type GeoclueLocation
  • func NewGeoclueLocation(objectPath dbus.ObjectPath) (GeoclueLocation, error)
• type GeoclueManager
  • func NewGeoclueManager() (GeoclueManager, error)

Constants

const (
	GeoclueAgentInterface = GeoclueInterface + ".Agent"

	GeoclueAgentObjectPath = GeoclueObjectPath + "/Agent"

	/* Methods */
	GeoclueAgentAuthorizeApp = GeoclueAgentInterface + ".AuthorizeApp"

	/* Property */
	GeoclueAgentPropertyMaxAccuracyLevel = GeoclueAgentInterface + ".MaxAccuracyLevel" // readable   u
)

Paths of methods and properties

const (
	GeoclueClientInterface  = GeoclueInterface + ".Client"
	GeoclueClientObjectPath = GeoclueObjectPath + "/Client"

	/* Methods */
	GeoclueClientStart = GeoclueClientInterface + ".Start"
	GeoclueClientStop  = GeoclueClientInterface + ".Stop"

	/* Property */
	GeoclueClientPropertyLocation               = GeoclueClientInterface + ".Location"               // readable   o
	GeoclueClientPropertyDistanceThreshold      = GeoclueClientInterface + ".DistanceThreshold"      // readwrite  u
	GeoclueClientPropertyTimeThreshold          = GeoclueClientInterface + ".TimeThreshold"          //  readwrite  u
	GeoclueClientPropertyDesktopId              = GeoclueClientInterface + ".DesktopId"              // readwrite  s
	GeoclueClientPropertyRequestedAccuracyLevel = GeoclueClientInterface + ".RequestedAccuracyLevel" // readwrite  u
	GeoclueClientPropertyActive                 = GeoclueClientInterface + ".Active"                 // readable   b

	/* SIGNAL */
	GeoclueClientSignalLocationUpdated = "LocationUpdated"
)

Paths of methods and properties

const (
	GeoclueLocationInterface = GeoclueInterface + ".Location"

	GeoclueLocationPropertyLatitude = GeoclueLocationInterface + ".Latitude" // readable   d

	GeoclueLocationPropertyLongitude = GeoclueLocationInterface + ".Longitude" // readable   d

	GeoclueLocationPropertyAccuracy = GeoclueLocationInterface + ".Accuracy" // readable   d

	GeoclueLocationPropertyAltitude = GeoclueLocationInterface + ".Altitude" // readable   d

	GeoclueLocationPropertySpeed = GeoclueLocationInterface + ".Speed" // readable   d

	GeoclueLocationPropertyHeading = GeoclueLocationInterface + ".Heading" // readable  d

	GeoclueLocationPropertyDescription = GeoclueLocationInterface + ".Description" // readable  s

	GeoclueLocationPropertyTimestamp = GeoclueLocationInterface + ".Timestamp" // readable   (tt)

)

Paths of methods and properties

const (
	GeoclueInterface         = "org.freedesktop.GeoClue2"
	GeoclueManagerInterface  = GeoclueInterface + ".Manager"
	GeoclueObjectPath        = "/org/freedesktop/GeoClue2"
	GeoclueManagerObjectPath = GeoclueObjectPath + "/Manager"

	/* Methods */
	GeoclueManagerGetClient    = GeoclueManagerInterface + ".GetClient"
	GeoclueManagerCreateClient = GeoclueManagerInterface + ".CreateClient"
	GeoclueManagerDeleteClient = GeoclueManagerInterface + ".DeleteClient"
	GeoclueManagerAddAgent     = GeoclueManagerInterface + ".AddAgent"

	/* Property */
	GeoclueManagerPropertyInUse                  = GeoclueManagerInterface + ".InUse"                  // readable   b
	GeoclueManagerPropertyAvailableAccuracyLevel = GeoclueManagerInterface + ".AvailableAccuracyLevel" //readable   u              // readable   ao
)

Paths of methods and properties

Types

type GClueAccuracyLevel

type GClueAccuracyLevel uint32

GClueAccuracyLevel is used to specify level of accuracy requested by, or allowed for a client.

const (
	GClueAccuracyLevelNone         GClueAccuracyLevel = 0 // Accuracy level unknown or unset.
	GClueAccuracyLevelCountry      GClueAccuracyLevel = 1 //Country-level accuracy.
	GClueAccuracyLevelCity         GClueAccuracyLevel = 4 //City-level accuracy.
	GClueAccuracyLevelNeighborhood GClueAccuracyLevel = 5 //neighborhood-level accuracy.
	GClueAccuracyLevelStreet       GClueAccuracyLevel = 6 //Street-level accuracy.
	GClueAccuracyLevelExact        GClueAccuracyLevel = 8 //Exact accuracy. Typically requires GPS receiver.

)

func (GClueAccuracyLevel) String

func (i GClueAccuracyLevel) String() string

type GeoclueAgent

type GeoclueAgent interface {

	//	This is the method that will be called by geoclue to get applications authorized to be given location information.
	//IN string desktop_id: The desktop file id (the basename of the desktop file) of the application requesting location information.
	//IN u req_accuracy_level: The level of location accuracy requested by client, as GClueAccuracyLevel.
	//OUT b authorized: Return value indicating if application should be given location information or not.
	//OUT u allowed_accuracy_level: The level of location accuracy allowed for client, as GClueAccuracyLevel.
	AuthorizeApp(string, GClueAccuracyLevel) (bool, GClueAccuracyLevel, error)

	/* PROPERTIES */
	// The global maximum level of accuracy allowed for all clients. Since agents are per-user, this can be different for each user. See GClueAccuracyLevel for possible values.
	GetMaxAccuracyLevel() (GClueAccuracyLevel, error)

	MarshalJSON() ([]byte, error)
}

GeoclueAgent interface all application-authorizing agents must implement. There must be a separate agent object for every logged-in user on path "/org/freedesktop/GeoClue2/Agent".

func NewGeoclueAgent

func NewGeoclueAgent() (GeoclueAgent, error)

NewGeoclueAgent returns new NewGeoclueAgent Interface

type GeoclueClient

type GeoclueClient interface {

	// Start receiving events about the current location. Applications should hook-up to
	// LocationUpdated" signal before calling this method.
	Start() error

	// Stop receiving events about the current location.
	Stop() error

	// Current location as path to a org.freedesktop.Geoclue2.Location object. Please note that this property will
	// be set to "/" (D-Bus equivalent of null) initially, until Geoclue finds user's location.
	// You want to delay reading this property until your callback to "LocationUpdated" signal is
	// called for the first time after starting the client.
	GetLocation() (GeoclueLocation, error)

	// Contains the current distance threshold in meters. This value is used by the service when it gets new location info.
	// If the distance moved is below the threshold, it won't emit the LocationUpdated signal. The default value is 0.
	// When TimeThreshold is zero, it always emits the signal.
	GetDistanceThreshold() (uint32, error)
	SetDistanceThreshold(uint32) error

	// Contains the current time threshold in seconds. This value is used by the service when it gets new location info.
	// If the time since the last update is below the threshold, it won't emit the LocationUpdated signal.
	// The default value is 0. When TimeThreshold is zero, it always emits the signal.
	GetTimeThreshold() (uint32, error)
	SetTimeThreshold(uint32) error

	// The desktop file id (the basename of the desktop file).
	// This property must be set by applications for authorization to work.
	// e.g. firefox
	GetDesktopId() (string, error)
	SetDesktopId(string) error

	// The level of accuracy requested by client, as GClueAccuracyLevel.
	// Please keep in mind that the actual accuracy of location information is dependent on available hardware on
	// your machine, external resources and/or how much accuracy user agrees to be comfortable with.
	GetRequestedAccuracyLevel() (GClueAccuracyLevel, error)
	SetRequestedAccuracyLevel(level GClueAccuracyLevel) error

	// If client is active, i-e started successfully using Start() and receiving location updates.
	// Please keep in mind that geoclue can at any time stop and start the client on user (agent) request.
	// Applications that are interested in in these changes, should watch for changes in this property.
	IsActive() (bool, error)

	MarshalJSON() ([]byte, error)

	// LocationUpdated signal: The signal is emitted every time the location changes. The client should set the
	// DistanceThreshold property to control how often this signal is emitted.
	// o old: old location as path to a #org.freedesktop.Geoclue2.Location object
	// o new: new location as path to a #org.freedesktop.Geoclue2.Location object
	SubscribeLocationUpdated() <-chan *dbus.Signal
	// Parse the signal and return the old and new Location
	ParseLocationUpdated(v *dbus.Signal) (oldLocation GeoclueLocation, newLocation GeoclueLocation, err error)

	Unsubscribe()
}

GeoclueClient interface you use to retrieve location information and receive location update signals from GeoClue service. You get the client object to use this interface on from org.freedesktop.GeoClue2.Manager.GetClient() method.

func NewGeoclueClient

func NewGeoclueClient(objectPath dbus.ObjectPath) (GeoclueClient, error)

NewGeoclueClient returns new GeoclueClient Interface

type GeoclueLocation

type GeoclueLocation interface {
	/* METHODS */
	// The latitude of the location, in degrees.
	GetLatitude() (float64, error)
	// The longitude of the location, in degrees.
	GetLongitude() (float64, error)
	// The accuracy of the location fix, in meters.
	GetAccuracy() (float64, error)
	// The altitude of the location fix, in meters. When unknown, its set to minimum double value, -1.7976931348623157e+308.
	GetAltitude() (float64, error)
	// The speed in meters per second. When unknown, it's set to -1.0.
	GetSpeed() (float64, error)
	// The heading direction in degrees with respect to North direction, in clockwise order. That means North becomes 0 degree, East: 90 degrees, South: 180 degrees, West: 270 degrees and so on. When unknown, it's set to -1.0.
	GetHeading() (float64, error)
	//A human-readable description of the location, if available. WARNING: Applications should not rely on this property since not all sources provide a description. If you really need a description (or more details) about current location, use a reverse-geocoding API, e.g geocode-glib.
	GetDescription() (string, error)
	//The timestamp when the location was determined, in seconds and microseconds since the Epoch. This is the time of measurement if the backend provided that information, otherwise the time when Geoclue received the new location.
	// Note that Geoclue can't guarantee that the timestamp will always monotonically increase, as a backend may not respect that. Also note that a timestamp can be very old, e.g. because of a cached location.
	GetTimestamp() (time.Time, error)
	MarshalJSON() ([]byte, error)
}

GeoclueLocation interface you use on location objects.

func NewGeoclueLocation

func NewGeoclueLocation(objectPath dbus.ObjectPath) (GeoclueLocation, error)

NewGeoclueLocation returns new NewGeoclueLocation Interface

type GeoclueManager

type GeoclueManager interface {

	// Retrieves a client object which can only be used by the calling application only.
	// On the first call from a specific D-Bus peer, this method will create the client object but subsequent
	// calls will return the path of the existing client.
	GetClient() (GeoclueClient, error)

	// Creates and retrieves a client object which can only be used by the calling application only.
	// Unlike GetClient(), this method always creates a new client.
	CreateClient() (GeoclueClient, error)

	// Use this method to explicitly destroy a client, created using GetClient() or CreateClient().
	// Long-running applications, should either use this to delete associated client(s) when not needed,
	// or disconnect from the D-Bus connection used for communicating with Geoclue (which is implicit
	// on client process termination).
	DeleteClient(GeoclueClient) error

	// An API for user authorization agents to register themselves. Each agent is responsible for the user
	// it is running as. Application developers can and should simply ignore this API.
	// IN s id: The Desktop ID (excluding .desktop) of the agent
	AddAgent(id string) error

	// Whether service is currently is use by any application.
	InUse() (bool, error)
	// The level of available accuracy, as GClueAccuracyLevel.
	GetAvailableAccuracyLevel() (GClueAccuracyLevel, error)

	MarshalJSON() ([]byte, error)
}

GeoclueManager interface you use to talk to main GeoClue2 manager object at path "/org/freedesktop/GeoClue2/Manager". The only thing you do with this interface is to call GetClient() or CreateClient() on it to get your application specific client object(s).

func NewGeoclueManager

func NewGeoclueManager() (GeoclueManager, error)

NewGeoclueManager returns new GeoclueManager Interface