Interface Connection.Interface.Renaming

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

Methods

RequestRename (s: Identifier) → nothing

Signals

Renamed (u: Original, u: New)
WARNING: This interface is not well-tested and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Objects implementing this interface must also implement:

Description

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.

Methods

(Permalink)

RequestRename (s: Identifier) → nothing

Parameters

  • 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 GetSelfHandle.

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.
    Rationale:
    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.

Signals

(Permalink)

Renamed (u: Original, u: New)

Parameters

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.