In some protocols, contacts can change their contact handle identifier
(the one passed to RequestHandles and returned
by InspectHandles). For example on the IRC
protocol, a user may change his/her "nick" (their Telepathy
handle) from sheeba to sheeba|afk.
This renaming is facilitated by the
Renaming interface.
The method RequestRename can be called to
change the string identifier for your own handle. This is used, for
example, to change your IRC nick.
The Renamed signal will be emitted for your
own handle id (the handle returned by
GetSelfHandle), as with any other handle
rename, so you don't need to special-case your own handle renaming in
the user interface view.
A given protocol may enforce certain rules with regards to possible
handles (valid characters), or whether your handle can be changed at
this time (e.g. IRC channels have a mode bit that disables rename while
you're a member). Thus RequestRename can
return several possible, non-fatal errors that should be reported to
the user.
Rename announcements depend on the protocol specification. Just holding
a handle or being in a channel which has that contact as a member may
not be enough to get the rename announcement.
For example, in IRC you must be a member of a chatroom with the user
to receive the rename notification.
Handle IDs are considered to be immutable, so when the identifier
changes, a new handle ID is issued.
When a contact changes its identifier,
the Renamed signal will be emitted providing
the original handle ID and a new ID for the contact.
If the contact is a member of channels that implement
Group (e.g. contact lists or chatrooms),
these will emit MembersChanged after
Renamed has been emitted. The reason
(Channel_Group_Change_Reason) will be given as Renamed.
