Properties — Telepathy D-Bus Interface Specification

# Interface Properties

Interface Index (Compact) | Summary | Description | Methods | Signals | Types

### Methods

GetProperties | (au: Properties) | → | a(uv): Values |
ListProperties | () | → | a(ussu): Available_Properties |
SetProperties | (a(uv): Properties) | → | nothing |

### Signals

PropertiesChanged | (a(uv): Properties) |
PropertyFlagsChanged | (a(uu): Properties) |

### Types

Property_ID | Simple Type | u |
Property_Flags | Flags | u |
Property_Spec | Struct | (ussu) |
Property_Flags_Change | Struct | (uu) |
Property_Value | Struct | (uv) |

Deprecated since 0.24.0. All uses of this interface have been expunged, and it may now be laid to rest.

### Description

Interface for channels and other objects, to allow querying and setting properties. ListProperties returns which properties are valid for the given channel, including their type, and an integer handle used to refer to them in GetProperties, SetProperties, and the PropertiesChanged signal. The values are represented by D-Bus variant types, and are accompanied by flags indicating whether or not the property is readable or writable.

Each property also has a flags value to indicate what methods are available. This is a bitwise OR of PropertyFlags values.

# Methods

(Permalink)

## GetProperties (au: Properties) → a(uv): Values

### Parameters

- Properties — au (Property_ID_List)
An array of property identifiers

### Returns

- Values — a(uv) (Property_Value_List)

An array of structs containing:

- integer identifiers
- variant boxed values

Returns an array of (identifier, value) pairs containing the current values of the given properties.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Invalid Argument
Some property identifier requested is invalid
- Permission Denied
Some property requested does not have the PROPERTY_FLAG_READ flag

(Permalink)

## ListProperties () → a(ussu): Available_Properties

### Returns

- Available_Properties — a(ussu) (Property_Spec_List)
An array of structs containing:

- an integer identifier
- a string property name
- a string representing the D-Bus signature of this property
- a bitwise OR of the flags applicable to this property

Returns a dictionary of the properties available on this channel.
(Permalink)

## SetProperties (a(uv): Properties) → nothing

### Parameters

- Properties — a(uv) (Property_Value_List)
An array mapping integer property identifiers to boxed values

Takes an array of (identifier, value) pairs containing desired values to set the given properties. In the case of any errors, no properties will be changed. When the changes have been acknowledged by the server, the PropertiesChanged signal will be emitted.

All properties given must have the PROPERTY_FLAG_WRITE flag, or PermissionDenied will be returned. If any variants are of the wrong type, NotAvailable will be returned. If any given property identifiers are invalid, InvalidArgument will be returned.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Not Available
Raised when the requested functionality is temporarily unavailable.
- Permission Denied
The user is not permitted to perform the requested operation.
- Network Error
Raised when there is an error reading from or writing to the network.

# Signals

(Permalink)

## PropertiesChanged (a(uv): Properties)

### Parameters

- Properties — a(uv) (Property_Value_List)

An array of structs containing:

- integer identifiers
- variant boxed values

The array should contain only properties whose values have actually changed.

Emitted when the value of readable properties has changed.
(Permalink)

## PropertyFlagsChanged (a(uu): Properties)

### Parameters

- Properties — a(uu) (Property_Flags_Change_List)

An array of structs containing:

- integer identifiers
- a bitwise OR of the current flags

The array should contain only properties whose flags have actually changed.

Emitted when the flags of some room properties have changed.

# Types

Simple Type (Permalink)

## Property_ID — u

An unsigned integer used to represent a Telepathy property.
Flags (Permalink)

## Property_Flags — u

- Read (1)
The property can be read
- Write (2)
The property can be written

Struct (Permalink)

## Property_Spec — (ussu)

A struct (property ID, property name, D-Bus signature, flags) representing a property, as returned by ListProperties on the Properties interface.

- Property_ID — u
- Name — s
- Signature — s (DBus_Signature)
- Flags — u (Property_Flags)

Struct (Permalink)

## Property_Flags_Change — (uu)

A struct (property ID, flags) representing a change to a property's flags, as seen in the PropertyFlagsChanged signal on the Properties interface.

- Property_ID — u
- New_Flags — u

Struct (Permalink)

## Property_Value — (uv)

A struct (property ID, value) representing a property's value, as seen in the PropertiesChanged signal on the Properties interface, returned by the GetProperties method and passed to the SetProperties method.

- Identifier — u (Property_ID)
- Value — v