Handle Renaming

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.

5.4.1. Changing Your Own Handle Name

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.

5.4.2. Receiving Renames

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.