Interface Connection.Interface.Renaming1

Interface Index (Compact) | Summary | Description | Methods | Signals


RequestRename (s: Identifier) nothing


Renamed (u: Original, u: New_Handle, s: New_Identifier)
Added in 0.27.3. (as stable API)
Objects implementing this interface must also implement:


An interface on connections to support protocols where the unique identifiers of contacts can change. Because handles are immutable, this is represented by a pair of handles, that representing the old name, and that representing the new one.



RequestRename (s: Identifier) → nothing


  • Identifier — s
  • The desired identifier

Request that the user's own identifier is changed on the server. If successful, a Renamed signal will be emitted for the current "self handle" as returned by the SelfHandle property.

It is protocol-dependent how the identifier that's actually used will be derived from the supplied identifier; some sort of normalization might take place.

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.
    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.
  • Network Error
  • Raised when there is an error reading from or writing to the network.
  • Not Available
  • Raised when the requested functionality is temporarily unavailable.
  • Invalid Argument
  • Raised when one of the provided arguments is invalid.
  • Permission Denied
  • The user is not permitted to perform the requested operation.



Renamed (u: Original, u: New_Handle, s: New_Identifier)


  • Original — u (Contact_Handle)
  • The handle of the original identifier
  • New_Handle — u (Contact_Handle)
  • The handle of the new identifier
  • New_Identifier — s
  • The normalized identifier corresponding to New_Handle.


    Providing this immediately means that client libraries can do useful things with this signal (log the change, construct contact objects, etc.) without an additional round-trip to find the corresponding string.

Emitted when the unique identifier of a contact on the server changes.

Any channels associated with the contact's original handle will continue to be to that handle, and so are no longer useful (unless the contact renames back, or another contact connects with that unique ID). Clients may open a similar channel associated with the new handle to continue communicating with the contact.

For example, if a GUI client associates text channels with chat windows, it should detach the old channel from the chat window, closing it, and associate a channel to the new handle with the same window.

If the contact's old handle is in any of the member lists of a channel which has the groups interface, it will be removed from the channel and the new handle will be added. The resulting MembersChanged signal must be emitted after the Renamed signal; the reason should be RENAMED.

The handles may be either general-purpose or channel-specific. If the original handle is general-purpose, the new handle must be general-purpose; if the original handle is channel-specific, the new handle must be channel-specific in the same channel.