org.freedesktop.realmd.Provider

org.freedesktop.realmd.Provider — a realm provider

Methods

Discover (IN  s     string,
          IN  a{sv} options,
          OUT i     relevance,
          OUT ao    realm);

Properties

Name     readable   s
Version  readable   s
Realms   readable   ao

Description

Various realm providers represent different software implementations that provide access to realms or domains.

This interface is implemented by individual providers, but is aggregated globally at the system bus name org.freedesktop.realmd with the object path /org/freedesktop/realmd

Method Details

The Discover() method

Discover (IN  s     string,
          IN  a{sv} options,
          OUT i     relevance,
          OUT ao    realm);

Discover realms for the given string. The input string is usually a domain or realm name, perhaps typed by a user. If an empty string is provided, the realm provider should try to discover a default realm, if possible (e.g. from DHCP).

options can contain, but is not limited to, the following values:

  • operation: a string identifier chosen by the client, which can then later be passed to Cancel() in order to cancel the operation

  • client-software: a string containing the client software identifier that the returned realms should match.

  • server-software: a string containing the client software identifier that the returned realms should match.

  • membership-software: a string containing the membership software identifier that the returned realms should match.

The relevance returned can be used to rank results from different discover calls to different providers. Implementors should return a positive number if the provider highly recommends that the realms be handled by this provider, or a zero if it can possibly handle the realms. Negative numbers should be returned if no realms are found.

This method does not return an error when no realms are discovered. It simply returns an empty realm list.

To see diagnostic information about the discovery process, connect to the org.freedesktop.realmd.Service::Diagnostics signal.

This method requires authorization for the PolicyKit action called org.freedesktop.realmd.discover-realm.

In addition to common DBus error results, this method may return:

  • org.freedesktop.realmd.Error.Failed: may be returned if the discovery could not be run for some reason.

  • org.freedesktop.realmd.Error.Cancelled: returned if the operation was cancelled.

  • org.freedesktop.realmd.Error.NotAuthorized: returned if the calling client is not permitted to perform a discovery operation.

IN s string:

an input string to discover realms for

IN a{sv} options:

options for the discovery operation

OUT i relevance:

the relevance of the returned results

OUT ao realm:

a list of realms discovered

Property Details

The "Name" property

Name  readable   s

the name of the provider The name of the provider. This is not normally displayed to the user, but may be useful for diagnostics or debugging.


The "Version" property

Version  readable   s

the version of the provider The version of the provider. This is not normally used in logic, but may be useful for diagnostics or debugging.


The "Realms" property

Realms  readable   ao

a list of realms A list of known, enrolled or discovered realms. All realms that this provider knows about are listed here. As realms are discovered they are added to this list.

Each realm is represented by the DBus object path of the realm object.