## 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.