Home · All Classes · All Namespaces · Modules · Functions · Files
Tp::Client::ConnectionInterface

ConnectionInterface Class Reference
[Connection proxies]

#include <TelepathyQt4/Connection>

Inherits Tp::AbstractInterface.

List of all members.

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Detailed Description

Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.Connection."

Constructor & Destructor Documentation

ConnectionInterface ( const QString &  busName,
const QString &  objectPath,
QObject *  parent = 0 
)

Creates a ConnectionInterface associated with the given object on the session bus.

Parameters:
busName Name of the service the object is on.
objectPath Path to the object on the service.
parent Passed to the parent class constructor.
ConnectionInterface ( const QDBusConnection &  connection,
const QString &  busName,
const QString &  objectPath,
QObject *  parent = 0 
)

Creates a ConnectionInterface associated with the given object on the given bus.

Parameters:
connection The bus via which the object can be reached.
busName Name of the service the object is on.
objectPath Path to the object on the service.
parent Passed to the parent class constructor.
ConnectionInterface ( Tp::DBusProxy *  proxy  ) 

Creates a ConnectionInterface associated with the same object as the given proxy.

Parameters:
proxy The proxy to use. It will also be the QObject::parent() for this object.

Member Function Documentation

static const char* staticInterfaceName (  )  [inline, static]

Returns the name of the interface "org.freedesktop.Telepathy.Connection", which this class represents.

Returns:
The D-Bus interface name.
uint SelfHandle (  )  const [inline]

Getter for the remote object property "SelfHandle".

Don't use this: it blocks the main loop.

Returns:
The value of the property, or a default-constructed value if the property is not readable.
QDBusPendingReply Connect (  )  [inline, slot]

Begins a call to the D-Bus method "Connect" on the remote object.

Request that the connection be established. This will be done asynchronously and errors will be returned by emitting <tp:member-ref>StatusChanged</tp:member-ref> signals.

Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.

QDBusPendingReply Disconnect (  )  [inline, slot]

Begins a call to the D-Bus method "Disconnect" on the remote object.

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

QDBusPendingReply<QStringList> GetInterfaces (  )  [inline, slot]

Begins a call to the D-Bus method "GetInterfaces" on the remote object.

Get the optional interfaces supported by this connection. Before the connection status changes to CONNECTED, the return from this method may change at any time, but it is guaranteed that interfaces will only be added, not removed. After the connection status changes to CONNECTED, the return from this method cannot change further.

There is no explicit change notification; reasonable behaviour for a client would be to retrieve the interfaces list once initially, and once more when it becomes CONNECTED.

<tp:rationale>

In some connection managers, certain capabilities of a connection are known to be implemented for all connections (e.g. support for SimplePresence), and some interfaces (like SimplePresence) can even be used before connecting. Other capabilities may or may not exist, depending on server functionality; by the time the connection goes CONNECTED, the connection manager is expected to have evaluated the server's functionality and enabled any extra interfaces for the remainder of the Connection's lifetime. </tp:rationale>

Returns:

An array of D-Bus interface names

QDBusPendingReply<QString> GetProtocol (  )  [inline, slot]

Begins a call to the D-Bus method "GetProtocol" on the remote object.

Get the protocol this connection is using.

Returns:

A string identifier for the protocol

QDBusPendingReply<uint> GetSelfHandle (  )  [inline, slot]

Begins a call to the D-Bus method "GetSelfHandle" on the remote object.

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal.

Returns:

The value of the SelfHandle property

QDBusPendingReply<uint> GetStatus (  )  [inline, slot]

Begins a call to the D-Bus method "GetStatus" on the remote object.

Get the current status as defined in the StatusChanged signal.

Returns:

An integer representing the current status

QDBusPendingReply HoldHandles ( uint  handleType,
const Tp::UIntList &  handles 
) [inline, slot]

Begins a call to the D-Bus method "HoldHandles" on the remote object.

Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the <tp:member-ref>RequestHandles</tp:member-ref> method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the <tp:member-ref>ReleaseHandles</tp:member-ref> method is called, or the clients disappear from the bus.

Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is "referenced" by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.

Parameters:
handleType The type of handle to be held
handles A array of integer handles to hold
QDBusPendingReply<QStringList> InspectHandles ( uint  handleType,
const Tp::UIntList &  handles 
) [inline, slot]

Begins a call to the D-Bus method "InspectHandles" on the remote object.

Return a string representation for a number of handles of a given type.

Parameters:
handleType The type of handle to be inspected
handles An array of integer handles of this type
Returns:

An array of identifiers corresponding to the given handles, in the same order.

QDBusPendingReply<Tp::ChannelInfoList> ListChannels (  )  [inline, slot]

Begins a call to the D-Bus method "ListChannels" on the remote object.

List all the channels which currently exist on this connection.

Returns:

An array of structs representing channels.

QDBusPendingReply ReleaseHandles ( uint  handleType,
const Tp::UIntList &  handles 
) [inline, slot]

Begins a call to the D-Bus method "ReleaseHandles" on the remote object.

Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See HoldHandles for notes.

Parameters:
handleType An integer handle type (as defined in RequestHandle)
handles An array of integer handles being held by the client
QDBusPendingReply<QDBusObjectPath> RequestChannel ( const QString &  type,
uint  handleType,
uint  handle,
bool  suppressHandler 
) [inline, slot]

Begins a call to the D-Bus method "RequestChannel" on the remote object.

Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.

On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).

If a new, empty channel is requested, on success the returned channel will always be an "anonymous" channel for which the type and handle are both zero.

If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> properties are the requested handle type and handle), or a newly created "anonymous" channel associated with the requested handle in some implementation-specific way.

For example, for a contact handle, the returned channel might be "anonymous", but implement the groups interface and have the requested contact already present among the members.

If the request cannot be satisfied, an error is raised and no channel is created.

Parameters:
type A D-Bus interface name representing base channel type
handleType An integer representing the handle type, or Handle_Type_None if no handle is specified
handle A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is Handle_Type_None
suppressHandler Clients SHOULD always set this to true. The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler. However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working. The channel dispatcher itself should set this to true too, so that it will ignore the NewChannel signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler. So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).
Returns:

The D-Bus object path for the channel created or retrieved

QDBusPendingReply<Tp::UIntList> RequestHandles ( uint  handleType,
const QStringList &  identifiers 
) [inline, slot]

Begins a call to the D-Bus method "RequestHandles" on the remote object.

Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The connection manager should record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the ReleaseHandles method. Where the identifier refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.

Parameters:
handleType The type of handle required
identifiers An array of identifiers of entities to request handles for
Returns:

An array of integer handle numbers in the same order as the given identifiers.

void SelfHandleChanged ( uint  selfHandle  )  [signal]

Represents the signal "SelfHandleChanged" on the remote object.

Emitted whenever the SelfHandle property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.

Parameters:
selfHandle The new value of the SelfHandle property.
void NewChannel ( const QDBusObjectPath &  objectPath,
const QString &  channelType,
uint  handleType,
uint  handle,
bool  suppressHandler 
) [signal]

Represents the signal "NewChannel" on the remote object.

Emitted when a new Channel object is created, either through user request or incoming information from the service.

Parameters:
objectPath A D-Bus object path for the channel object on this service
channelType A D-Bus interface name representing the channel type
handleType An integer representing the type of handle this channel communicates with, or Handle_Type_None if no handle is specified
handle A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified
suppressHandler 

If true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no other handler should be launched. Clients MAY assume that channels where this is true were created by a user request.

If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself (this usage is deprecated).

Clients MUST NOT assume that only incoming channels will have this flag set to false.

void ConnectionError ( const QString &  error,
const QVariantMap &  details 
) [signal]

Represents the signal "ConnectionError" on the remote object.

Emitted when an error occurs that renders this connection unusable.

Whenever this signal is emitted, it MUST immediately be followed by a <tp:member-ref>StatusChanged</tp:member-ref> signal with status Connection_Status_Reason_Disconnected and an appropriate reason code.

Connection managers SHOULD emit this signal on disconnection, but need not do so. Clients MUST support connection managers that emit StatusChanged(Disconnected, ...) without first emitting ConnectionError.

<tp:rationale>

This signal provides additional information about the reason for disconnection. The reason for connection is always straightforward - it was requested - so it does not need further explanation. However, on errors, it can be useful to provide additional information.

The <tp:type>Connection_Status_Reason</tp:type> is not given here, since it will be signalled in <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client implementation would be to store the information given by this signal until StatusChanged is received, at which point the information given by this signal can be used to supplement the StatusChanged signal. </tp:rationale>

Parameters:
error The name of a D-Bus error describing the error that occurred, which may correspond to a Connection_Status_Reason, or may be a more specific Telepathy error (such as org.freedesktop.Telepathy.Errors.ConnectionRefused for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. For instance, a SIP connection manager could signal "402 Payment Required" as an error in a connection-manager-specific namespace, or a link-local XMPP implementation that used Avahi could provide the error given to it by the avahi-daemon.
details 

Additional information about the error, which may include the following well-known keys:

debug-message (s)
Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances

<tp:rationale>

This argument allows for future extensions. For instance, if indicating DNS lookup failure, we could define a key that indicates the hostname that could not be found. </tp:rationale>

void StatusChanged ( uint  status,
uint  reason 
) [signal]

Represents the signal "StatusChanged" on the remote object.

Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

Parameters:
status An integer indicating the new status, as defined by ConnectionStatus
reason An integer indicating the reason for the status change, as defined by ConnectionStatusReason
virtual void invalidate ( Tp::DBusProxy *  ,
const QString &  ,
const QString &   
) [protected, virtual]

Property Documentation

uint SelfHandle [read]

Represents property "SelfHandle" on the remote object.

The handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the SelfHandleChanged signal. If the connection is not yet in the CONNECTED state, the value of this property MAY be zero.

Copyright © 2009 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.2.1