Package org.linphone.core
Interface ChatRoom
public interface ChatRoom
A chat room is the place where
To create (or find) a
object. A chat room is uniquely identified by it's local and remote SIP
addresses, meaning you can only have one chat room between two accounts (unless
the backend is
or
Be careful as a
created asynchronously, so make sure you add a
returned object to be notified when it will be in state
All chat rooms are loaded from database when the
can get them using
chat rooms nor ones for which the local address doesn't match an existing
section of your configuration file by setting hide_empty_chat_rooms=0 and/or
hide_chat_rooms_from_removed_proxies=0.
ChatMessage
are exchanged. To create (or find) a
ChatRoom
, you first need a ChatRoomParams
object. A chat room is uniquely identified by it's local and remote SIP
addresses, meaning you can only have one chat room between two accounts (unless
the backend is
ChatRoom.Backend.FlexisipChat
). Then you can call Core.searchChatRoom(org.linphone.core.ChatRoomParams, org.linphone.core.Address, org.linphone.core.Address, org.linphone.core.Address[])
or
Core.createChatRoom(org.linphone.core.ChatRoomParams, org.linphone.core.Address, org.linphone.core.Address[])
.Be careful as a
ChatRoom.Backend.FlexisipChat
backend ChatRoom
will becreated asynchronously, so make sure you add a
ChatRoomListener
to thereturned object to be notified when it will be in state
ChatRoom.State.Created
.All chat rooms are loaded from database when the
Core
starts, and youcan get them using
Core.getChatRooms()
. This method doesn't return emptychat rooms nor ones for which the local address doesn't match an existing
ProxyConfig
identity, unless you specify otherwise in the [misc]section of your configuration file by setting hide_empty_chat_rooms=0 and/or
hide_chat_rooms_from_removed_proxies=0.
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic enum
static enum
static enum
static enum
static enum
static enum
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(ChatRoomListener listener) void
addParticipant
(Address addr) Add a participant to a chat room.boolean
addParticipants
(Address[] addresses) Add several participants to a chat room at once.void
Allow cpim on a basic chat room .void
Allow multipart on a basic chat room .boolean
Tells whether a chat room is able to handle participants.void
compose()
Notifies the destination of the chat message being composed that the user is
typing a new message.Creates an empty message attached to the given chat room.createFileTransferMessage
(Content initialContent) Creates a message attached to the given chat room with a particular content.createForwardMessage
(ChatMessage message) Creates a forward message attached to the given chat room with a particular
message.createMessage
(String message) Deprecated.01/07/2020.createMessageFromUtf8
(String message) Creates a message attached to the given chat room with a plain text content
filled with the given message.createReplyMessage
(ChatMessage message) Creates a reply message attached to the given chat room with a particular
message.createVoiceRecordingMessage
(Recorder recorder) Creates a chat message with a voice recording attached to the given chat room.void
Delete all messages from the history.void
deleteMessage
(ChatMessage message) Delete a message from the chat room history.boolean
Uses linphone spec to check if all participants support ephemeral messages.findMessage
(String messageId) Gets the chat message sent or received in this chat room that matches the
message_id.findParticipant
(Address address) Find a participant of a chat room from its address.getCall()
Gets the current call associated to this chatroom if any To commit a message,
useChatMessage.send()
int
Get the capabilities of a chat room.int
getChar()
When realtime text is enabledCallParams#realtimeTextEnabled
,
LinphoneCoreIsComposingReceivedCb is call everytime a char is received from
peer.Address[]
Gets the list of participants that are currently composing.Get the conference address of the chat room.getCore()
Returns back pointer toCore
object.long
Return the creation time for the chat room.Returns current parameters associated with the chat room.long
Get lifetime (in seconds) for all new ephemeral messages in the chat room.Get the ephemeral mode of the chat room.getHistory
(int nbMessage) Gets nb_message most recent messages from chat_room chat room, sorted from
oldest to most recent.EventLog[]
getHistoryEvents
(int nbEvents) Gets nb_events most recent events from chat_room chat room, sorted from oldest
to most recent.int
Gets the number of events in a chat room.EventLog[]
getHistoryMessageEvents
(int nbEvents) Gets nb_events most recent chat message events from chat_room chat room, sorted
from oldest to most recent.getHistoryRange
(int begin, int end) Gets the partial list of messages in the given range, sorted from oldest to
most recent.EventLog[]
getHistoryRangeEvents
(int begin, int end) Gets the partial list of events in the given range, sorted from oldest to most
recent.EventLog[]
getHistoryRangeMessageEvents
(int begin, int end) Gets the partial list of chat message events in the given range, sorted from
oldest to most recent.int
Gets the number of messages in a chat room.Gets the last chat message sent or received in this chat room.long
Return the last updated time for the chat room.Get the local address associated to this chat room.getMe()
Get the participant representing myself in the chat room.boolean
getMuted()
Gets if a chat room has been flagged as muted (not by default).long
Gets the native pointer used by this class to make native method calls.int
Get the number of participants in the chat room (that is without ourselves).Get the list of participants of a chat room.Get the peer address associated to this chat room.Get the security level of a chat room.getState()
Get the state of the chat room.Get the subject of a chat room.Gets all unread messages for this chat room, sorted from oldest to most recent.int
Gets the number of unread messages in the chatroom.Gets the object stored in this object user's databoolean
Deprecated.16/03/2022 useisReadOnly()
instead.boolean
hasCapability
(int mask) Check if a chat room has given capabilities.boolean
isEmpty()
boolean
Returns whether or not the ephemeral message feature is enabled in the chat
room.boolean
Return whether or not a message can be sent using this chat room.boolean
Tells whether the remote is currently composing a message.void
leave()
Leave a chat room.void
Mark all messages of the conversation as read.void
notifyParticipantDeviceRegistration
(Address participantDevice) Notify the chatroom that a participant device has just registered.void
receiveChatMessage
(ChatMessage message) Used to receive a chat message when using async mechanism with IM
enchat_roomyption engine.void
removeListener
(ChatRoomListener listener) void
removeParticipant
(Participant participant) Remove a participant of a chat room.void
removeParticipants
(Participant[] participants) Remove several participants of a chat room at once.void
setConferenceAddress
(Address conferenceAddress) Set the conference address of a group chat room.void
setEphemeralEnabled
(boolean enable) Enable or disable the ephemeral message feature in the chat room.void
setEphemeralLifetime
(long time) Set lifetime (in seconds) for all new ephemeral messages in the chat room.void
Set the ephemeral mode of the chat room.void
setMuted
(boolean muted) Sets if a chat room should be considered as muted or not.void
setParticipantAdminStatus
(Participant participant, boolean isAdmin) Change the admin status of a participant of a chat room (you need to be an
admin yourself to do this).void
setParticipantDevices
(Address participantAddress, ParticipantDeviceIdentity[] deviceIdentities) Set the list of participant devices in the form of SIP URIs with GRUUs for a
given participant.void
setSubject
(String subject) Set the subject of a chat room.void
setUserData
(Object data) Sets the object to store in this object user's datastateToString
(ChatRoom.State state) Converts aChatRoom.State
enum to a string.toString()
-
Method Details
-
getCall
Gets the current call associated to this chatroom if any To commit a message,
useChatMessage.send()
- Returns:
Call
or null.
-
getCapabilities
int getCapabilities()Get the capabilities of a chat room.
- Returns:
- The capabilities of the chat room (as a
LinphoneChatRoomCapabilitiesMask)
-
getChar
int getChar()When realtime text is enabledCallParams#realtimeTextEnabled
,
LinphoneCoreIsComposingReceivedCb is call everytime a char is received from
peer.
At the end of remote typing a regularChatMessage
is received with
committed data from LinphoneCoreCbsMessageReceivedCb.- Returns:
- RFC 4103/T.140 char
-
getComposingAddresses
Gets the list of participants that are currently composing.
- Returns:
- List of addresses that are in the is_composing state.
-
getConferenceAddress
Get the conference address of the chat room.
- Returns:
- The conference address of the chat room or null if this type of chat
room is not conference based.
-
setConferenceAddress
Set the conference address of a group chat room.
This function needs to be called from the
LinphoneChatRoomCbsConferenceAddressGenerationCb callback and only there. This
function is meaningful only for server implementation of chatroom, and shall
not by used by client applications.- Parameters:
conferenceAddress
- The conferenceAddress
to be used by the group
chat room
-
getCore
- Returns:
- the
Core
object this chat room is attached to.
-
getCreationTime
long getCreationTime()Return the creation time for the chat room.
- Returns:
- the time at which the chat room was created
-
getCurrentParams
Returns current parameters associated with the chat room.
This is typically the parameters passed at chat room chat_roomeation to
linphone_core_chat_roomeate_chat_room() or some default parameters if noChatRoomParams
was explicitely passed during chat room chat_roomeation.- Returns:
- the current
ChatRoomParams
parameters.
-
isEphemeralEnabled
boolean isEphemeralEnabled()Returns whether or not the ephemeral message feature is enabled in the chat
room.
- Returns:
- true if ephemeral is enabled, false otherwise.
-
setEphemeralEnabled
void setEphemeralEnabled(boolean enable) Enable or disable the ephemeral message feature in the chat room.
Works only for flexisip-based chat room. An ephemeral message will
automatically disappear from the sender and recipient's chatrooms after a
specified timeout configurable withsetEphemeralLifetime(long)
. The timer
starts when the message has been displayed at the recipent, which means:- Parameters:
enable
- true if the ephemeral message feature is enabled, false
otherwise.
-
getEphemeralLifetime
long getEphemeralLifetime()Get lifetime (in seconds) for all new ephemeral messages in the chat room.
After the message is read, it will be deleted after "time" seconds. see:#ephemeralEnabled
- Returns:
- the ephemeral lifetime (in secoonds)
-
setEphemeralLifetime
void setEphemeralLifetime(long time) Set lifetime (in seconds) for all new ephemeral messages in the chat room.
After the message is read, it will be deleted after "time" seconds. see:#ephemeralEnabled
- Parameters:
time
- The ephemeral lifetime, default is 0 (disabled)
warning: A value of "time" equal to 0 disables ephemeral messages
-
getEphemeralMode
ChatRoom.EphemeralMode getEphemeralMode()Get the ephemeral mode of the chat room.
see:#ephemeralEnabled
- Returns:
- the ephemeral mode
ChatRoom.EphemeralMode
-
setEphemeralMode
Set the ephemeral mode of the chat room.
see:#ephemeralEnabled
- Parameters:
mode
- The ephemeral modeChatRoom.EphemeralMode
warning: This function only changes the mode of ephemeral messagesChatRoom.EphemeralMode
. It is required to manually enable ephemeral messages after setting the mode
by calling#enableEphemeral
-
getHistoryEventsSize
int getHistoryEventsSize()Gets the number of events in a chat room.
- Returns:
- the number of events.
-
getHistorySize
int getHistorySize()Gets the number of messages in a chat room.
- Returns:
- the number of messages.
-
isEmpty
boolean isEmpty()- Returns:
- true if there are no
ChatMessage
, false otherwise.
-
isReadOnly
boolean isReadOnly()Return whether or not a message can be sent using this chat room.
A chat room may be read only until it's created, or when it's a group you have
left.- Returns:
- true if a chat message can't be sent in it, false otherwise.
-
isRemoteComposing
boolean isRemoteComposing()Tells whether the remote is currently composing a message.
- Returns:
- true if the remote is currently composing a message, false otherwise.
-
getLastMessageInHistory
Gets the last chat message sent or received in this chat room.
- Returns:
- the latest
ChatMessage
or null if no message.
-
getLastUpdateTime
long getLastUpdateTime()Return the last updated time for the chat room.
- Returns:
- the last updated time
-
getLocalAddress
Get the local address associated to this chat room.
- Returns:
- The local address.
-
getMe
Get the participant representing myself in the chat room.
- Returns:
- The participant representing myself in the conference or null if me is
not set.
-
getMuted
boolean getMuted()Gets if a chat room has been flagged as muted (not by default).
A muted chat room isn't used to compute unread messages total count.- Returns:
- true if the chat room is muted, false otherwise.
-
setMuted
void setMuted(boolean muted) Sets if a chat room should be considered as muted or not.
A muted chat room isn't used to compute unread messages total count.- Parameters:
muted
- true to flag it as muted, false to un-mute it.
-
getNbParticipants
int getNbParticipants()Get the number of participants in the chat room (that is without ourselves).
- Returns:
- The number of participants in the chat room
-
getParticipants
Get the list of participants of a chat room.
- Returns:
- A of the participants
-
getPeerAddress
Get the peer address associated to this chat room.
- Returns:
- The peer address.
-
getSecurityLevel
ChatRoom.SecurityLevel getSecurityLevel()Get the security level of a chat room.
- Returns:
- The current
ChatRoom.SecurityLevel
of the chat room
-
getState
ChatRoom.State getState()Get the state of the chat room.
- Returns:
- The current
ChatRoom.State
of the chat room
-
getSubject
Get the subject of a chat room.
- Returns:
- The subject of the chat room.
-
setSubject
Set the subject of a chat room.
- Parameters:
subject
- The new subject to set for the chat room
-
getUnreadHistory
Gets all unread messages for this chat room, sorted from oldest to most recent.
- Returns:
- A list of unread chat messages.
-
getUnreadMessagesCount
int getUnreadMessagesCount()Gets the number of unread messages in the chatroom.
- Returns:
- the number of unread messages.
-
addParticipant
Add a participant to a chat room.
This may fail if this type of chat room does not handle participants. Use
canHandleParticipants()
to know if this chat room handles participants.- Parameters:
addr
- The address of the participant to add to the chat room
-
addParticipants
Add several participants to a chat room at once.
This may fail if this type of chat room does not handle participants. Use
canHandleParticipants()
to know if this chat room handles participants.- Parameters:
addresses
- The participants to add.- Returns:
- true if everything is OK, false otherwise
-
allowCpim
void allowCpim()Allow cpim on a basic chat room .
-
allowMultipart
void allowMultipart()Allow multipart on a basic chat room .
-
canHandleParticipants
boolean canHandleParticipants()Tells whether a chat room is able to handle participants.
- Returns:
- true if the chat room can handle participants, false otherwise
-
compose
void compose()Notifies the destination of the chat message being composed that the user is
typing a new message.
-
createEmptyMessage
Creates an empty message attached to the given chat room.
- Returns:
- a new
ChatMessage
-
createFileTransferMessage
Creates a message attached to the given chat room with a particular content.
UseChatMessage.send()
to initiate the transfer- Parameters:
initialContent
-Content
initial content.- Returns:
- a new
ChatMessage
-
createForwardMessage
Creates a forward message attached to the given chat room with a particular
message.
- Parameters:
message
-ChatMessage
message to be forwarded.- Returns:
- a new
ChatMessage
-
createMessage
Deprecated.01/07/2020. UsecreateMessageFromUtf8(java.lang.String)
instead.Creates a message attached to the given chat room with a plain text content
filled with the given message.
- Parameters:
message
- text message, null if absent.- Returns:
- a new
ChatMessage
-
createMessageFromUtf8
Creates a message attached to the given chat room with a plain text content
filled with the given message.
Introduced in 01/07/2020- Parameters:
message
- text message in UTF8, null if absent.- Returns:
- a new
ChatMessage
-
createReplyMessage
Creates a reply message attached to the given chat room with a particular
message.
- Parameters:
message
-ChatMessage
message to reply to.- Returns:
- a new
ChatMessage
-
createVoiceRecordingMessage
Creates a chat message with a voice recording attached to the given chat room.
warning: If the recorder isn't in Closed state, it will return an empty
message!- Parameters:
recorder
- theRecorder
object used to record the voice message.- Returns:
- a new
ChatMessage
-
deleteHistory
void deleteHistory()Delete all messages from the history.
-
deleteMessage
Delete a message from the chat room history.
- Parameters:
message
- TheChatMessage
object to remove.
-
ephemeralSupportedByAllParticipants
boolean ephemeralSupportedByAllParticipants()Uses linphone spec to check if all participants support ephemeral messages.
It doesn't prevent to send ephemeral messages in the room but those who don't
support it won't delete messages after lifetime has expired. see:#ephemeralEnabled
- Returns:
- true if all participants in the chat room support ephemeral messages,
false otherwise
-
findMessage
Gets the chat message sent or received in this chat room that matches the
message_id.
- Parameters:
messageId
- The id of the message to find- Returns:
- the
ChatMessage
if found or null.
-
findParticipant
Find a participant of a chat room from its address.
- Parameters:
address
- TheAddress
to search in the list of participants of the
chat room- Returns:
- The participant if found, null otherwise.
-
getHistory
Gets nb_message most recent messages from chat_room chat room, sorted from
oldest to most recent.
- Parameters:
nbMessage
- Number of message to retrieve. 0 means everything.- Returns:
- A list of chat messages.
-
getHistoryEvents
Gets nb_events most recent events from chat_room chat room, sorted from oldest
to most recent.
- Parameters:
nbEvents
- Number of events to retrieve. 0 means everything.- Returns:
- The list of the most recent events.
-
getHistoryMessageEvents
Gets nb_events most recent chat message events from chat_room chat room, sorted
from oldest to most recent.
- Parameters:
nbEvents
- Number of events to retrieve. 0 means everything.- Returns:
- A list
-
getHistoryRange
Gets the partial list of messages in the given range, sorted from oldest to
most recent.
- Parameters:
begin
- The first message of the range to be retrieved. History most
recent message has index 0.end
- The last message of the range to be retrieved. History oldest
message has index of history size - 1 (usegetHistorySize()
to retrieve
history size)- Returns:
- A list of chat messages.
-
getHistoryRangeEvents
Gets the partial list of events in the given range, sorted from oldest to most
recent.
- Parameters:
begin
- The first event of the range to be retrieved. History most recent
event has index 0.end
- The last event of the range to be retrieved. History oldest event
has index of history size - 1- Returns:
- The list of the found events.
-
getHistoryRangeMessageEvents
Gets the partial list of chat message events in the given range, sorted from
oldest to most recent.
- Parameters:
begin
- The first event of the range to be retrieved. History most recent
event has index 0.end
- The last event of the range to be retrieved. History oldest event
has index of history size - 1- Returns:
- The list of chat message events.
-
hasBeenLeft
Deprecated.16/03/2022 useisReadOnly()
instead.Return whether or not the chat room has been left.
- Returns:
- true if the chat room has been left, false otherwise.
-
hasCapability
boolean hasCapability(int mask) Check if a chat room has given capabilities.
- Parameters:
mask
- a LinphoneChatRoomCapabilitiesMask mask- Returns:
- true if the mask matches, false otherwise
-
leave
void leave()Leave a chat room.
-
markAsRead
void markAsRead()Mark all messages of the conversation as read.
-
notifyParticipantDeviceRegistration
Notify the chatroom that a participant device has just registered.
This function is meaningful only for server implementation of chatroom, and
shall not by used by client applications.- Parameters:
participantDevice
- list of the participant devices to be used by the
group chat room
-
receiveChatMessage
Used to receive a chat message when using async mechanism with IM
enchat_roomyption engine.
- Parameters:
message
-ChatMessage
object
-
removeParticipant
Remove a participant of a chat room.
- Parameters:
participant
- The participant to remove from the chat room
-
removeParticipants
Remove several participants of a chat room at once.
- Parameters:
participants
- The participants to remove.
-
setParticipantAdminStatus
Change the admin status of a participant of a chat room (you need to be an
admin yourself to do this).
- Parameters:
participant
- The Participant for which to change the admin statusisAdmin
- A boolean value telling whether the participant should now be an
admin or not
-
setParticipantDevices
void setParticipantDevices(@NonNull Address participantAddress, @NonNull ParticipantDeviceIdentity[] deviceIdentities) Set the list of participant devices in the form of SIP URIs with GRUUs for a
given participant.
This function is meaningful only for server implementation of chatroom, and
shall not by used by client applications.- Parameters:
participantAddress
- The participant addressdeviceIdentities
- List of the participant devices to be used by the group
chat room
-
stateToString
- Parameters:
state
- aChatRoom.State
to convert to string- Returns:
- the string representation of the
ChatRoom.State
-
addListener
-
removeListener
-
setUserData
Sets the object to store in this object user's data- Parameters:
data
- the object to store
-
getUserData
Object getUserData()Gets the object stored in this object user's data- Returns:
- the object store if any, null otherwise
-
getNativePointer
long getNativePointer()Gets the native pointer used by this class to make native method calls.- Returns:
- the nativer pointer, as long
-
toString
String toString()
-