Detailed Description
The QCollectivePresence class defines a generic interface to presence information.
The QCollectivePresence class inherits QAbstractIpcInterface which provides client/server communications framework.
The QCollectivePresence in Server mode parses the presence data received from the network and informs the rest of the system upon changes to the peers' presence for a certain type of service.
For example, to implement the server mode provider that provides presence interface in "voip" service, create a class that inherits QCollectivePresence class and override public slots.
class PresenceProvider : public QCollectivePresence
{
Q_OBJECT
public:
PresenceProvider( QObject *parent=0 )
: QCollectivePresence( "voip", parent, Server )
{
...
}
public slots:
virtual void subscribePeer( const QString &uri )
{
...
}
...
};
The QCollectivePresence in Client mode is used by client applications to access the presence data for both local and remote peers for the type of service that the server mode provides.
To start monitoring a list of peers from a client application, for example:
QCollectivePresence *provider = new QCollectivePresence( "voip" );
foreach ( QString id, voipIds ) {
provider->subscribePeer(id);
}
Property Documentation
protocol : const QString
This property holds the name of the protocol supported by this presence service.
The server implentation needs to make sure to set the protocol name in the constructor using QAbstractIpcInterface::setValue() function with the key "protocol".
PresenceProviderServer::PresenceProviderServer
( const QString &service, QObject *parent, QAbstractIpcInterface::Mode mode )
: QCollectivePresence( service, parent, Server )
{
...
setValue( "Protocol", "SIP" );
...
}
Access functions:
- QString protocol () const
Member Function Documentation
QCollectivePresence::QCollectivePresence ( const QString & service = QString(), QObject * parent = 0, QAbstractIpcInterface::Mode mode = Client )
Constructs a QCollectivePresence object for service and attaches it to parent. The object will be created in client mode if mode is Client, or server mode otherwise.
If service is empty, this class will use the first available service that supports presence. If there is more than one service that supports presence, the caller should enumerate them with QCommServiceManager::supports() and create separate QCollectivePresence objects for each.
See also QCommServiceManager::supports().
QCollectivePresence::~QCollectivePresence ()
Destroys the QCollectivePresence object.
void QCollectivePresence::authorizePeer ( const QString & uri ) [virtual slot]
Authorizes the pending presence subscription request from remote peer uri. If there is no pending request from uri, then this method has no effect.
The publishedPeersChanged() signal will be emitted once the service adds the uri to the publish list.
See also denyPeer().
void QCollectivePresence::blockPeer ( const QString & uri ) [virtual slot]
Attempts to temporarily block a peer uri from receiving local presence information. Some protocol implementations might not support this functionality.
The blockedPeersChanged() signal will be emitted once the peer has been blocked.
See also blockedPeers(), blockedPeersChanged(), and unblockPeer().
QStringList QCollectivePresence::blockedPeers () const
Returns a list of peers which are temporarily blocked from receiving local presence information.
See also blockPeer(), unblockPeer(), and blockedPeersChanged().
void QCollectivePresence::blockedPeersChanged () [signal]
This signal is emitted whenever a peer has been added or removed from the blocked peers list. Blocked peers will temporarily not receive any presence information.
void QCollectivePresence::denyPeer ( const QString & uri ) [virtual slot]
Denies the pending presence subscription request from remote peer uri. If there is no pending request from uri, this method has no effect.
See also authorizePeer().
Returns the presence information currently set for this service for the local user.
See also localPresenceChanged().
void QCollectivePresence::localPresenceChanged () [signal]
This signal is emitted whenever the local user's presence has been changed.
See also localInfo().
Returns the presence information for a remote peer given by uri.
See also peerPresencesChanged().
void QCollectivePresence::peerPresencesChanged ( const QStringList & presences ) [signal]
This signal is emitted whenever the presence service receives notification of a change in presence status. The uris of the members with changed presence status is given in presences.
See also peerInfo().
QStringList QCollectivePresence::pendingPeerSubscriptions () const
Returns a list of peer uris which have been sent a subscription request by the local client, but where the remote peer has not authorized to publish its presence to the local peer.
See also pendingPeerSubscriptionsChanged().
void QCollectivePresence::pendingPeerSubscriptionsChanged () [signal]
This signal is emitted whenever a peer has been sent a subscribe request, but the request has not been accepted, denied or rescinded.
See also subscribePeer().
QStringList QCollectivePresence::pendingPublishRequests () const
Returns a list of peer uris which have sent a subscribe request for local presence information, but which haven't been rescinded, denied using denyPeer() or accepted using authorizePeer(). Once the request is accepted using authorizePeer() the local presence information will be published to the remote peer.
Only protocols which support publish lists will implement this method.
See also pendingPublishRequestsChanged().
void QCollectivePresence::pendingPublishRequestsChanged () [signal]
This signal is emitted whenever a subscription request has been received. The user can accept this subscription by using the authorizePeer() method, in which case the user's presence information will be published to the remote peer. The publishedPeersChanged() signal will be emitted once the peer has been added to the publish list successfully.
The user can deny the subscription request by using the denyPeer() method. This will refuse the subscription request.
For protocols that do not use user-confirmed subscriptions, this signal is not used.
See also denyPeer() and authorizePeer().
void QCollectivePresence::publishPeerInfo ( const QCollectivePresenceInfo & info ) [protected]
This is a convenience method designed to be used by presence service implementations in order to publish peer presence info so that it can be accessed by Client mode QCollectivePresence objects.
QStringList QCollectivePresence::publishedPeers () const
Returns a list of peer uris who receive local presence information.
See also authorizePeer(), denyPeer(), and publishedPeersChanged().
void QCollectivePresence::publishedPeersChanged () [signal]
This signal is emitted whenever the list of peers who receive local presence information has changed. This usually happens when authorizePeer() method has added the remote peer to the publish list successfully.
See also authorizePeer(), denyPeer(), and pendingPublishRequestsChanged().
void QCollectivePresence::removePeerInfo ( const QString & uri ) [protected]
Removes the peer info with uri from storage. The current implementation removes the storage value from ValueSpace by using removeValue() function.
void QCollectivePresence::setLocalPresence ( const QCollectivePresenceInfo & info ) [virtual slot]
Attempts to set the local presence information published by this service to info. Note that the avatar field will be ignored when setting the presence information. To set the avatar, use the regular PIM mechanisms.
The localPresenceChanged() signal will be emitted once the local presence information has been updated.
Returns a dictionary of supported presence statuses mapped to a presence type. This can be used by client applications to display the appropriate icon for the specific status.
Please note that the "Offline" state is not settable on the local account.
See also setLocalPresence().
void QCollectivePresence::subscribePeer ( const QString & uri ) [virtual slot]
Attempts to subscribe to presence information of peer uri. The subscribedPeersChanged() signal will be emitted whenever the list changes. Client applications should monitor this list to find out when the desired peer uri has been added to the subscribed list. From then on the presence information will be available using peerInfo().
See also unsubscribePeer().
QStringList QCollectivePresence::subscribedPeers () const
Returns a list of peer uris for which presence information is available.
See also subscribePeer(), unsubscribePeer(), and subscribedPeersChanged().
void QCollectivePresence::subscribedPeersChanged () [signal]
This signal is emitted whenever a new peer has been added to the subscribe list (e.g. a remote user has accepted a subscribe request).
See also subscribePeer() and unsubscribePeer().
void QCollectivePresence::unblockPeer ( const QString & uri ) [virtual slot]
Attempts to remove a peer uri from the blocked peers list. Attempts to unblock peers which are not blocked will be ignored.
The blockedPeersChanged() signal will be emitted once the peer has been unblocked.
See also blockedPeers(), blockPeer(), and blockedPeersChanged().
void QCollectivePresence::unsubscribePeer ( const QString & uri ) [virtual slot]
Attempts to unsubscribe from presence information published by peer uri.
See also subscribePeer().
