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

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