Package org.linphone.core

Interface ChatMessage

public interface ChatMessage
A ChatMessage represents an instant message that can be send or
received through a ChatRoom.

To create a ChatMessage, use ChatRoom.createEmptyMessage(), then
either add text using addUtf8TextContent(java.lang.String) or a Content with
file informations using addFileContent(org.linphone.core.Content). A valid Content for
file transfer must contain a type and subtype, the name of the file and it's
size. Finally call send() to send it.
To send files through a ChatMessage, you need to have configured a file
transfer server URL with Core.setFileTransferServer(java.lang.String). On the receiving
side, either use downloadContent(org.linphone.core.Content) to download received files or enable
auto-download in the Core using Core.setMaxSizeForAutoDownloadIncomingFiles(int)
, -1 disabling the feature and 0 always downloading files no matter it's size.
Keep in mind a ChatMessage created by a {@link ChatRoom#Backend#Basic}
ChatRoom can only contain one Content, either text or file.

  • Method Details

    • getAppdata

      @Nullable String getAppdata()
      Linphone message has an app-specific field that can store a text.

      The application might want to use it for keeping data over restarts, like
      thumbnail image path.
      Returns:
      the application-specific data or null if none has been stored.

    • setAppdata

      void setAppdata(@Nullable String data)
      Linphone message has an app-specific field that can store a text.

      The application might want to use it for keeping data over restarts, like
      thumbnail image path.
      Invoking this function will attempt to update the message storage to reflect
      the change if it is enabled.
      Parameters:
      data - the data to store into the message.

    • getCallId

      @NonNull String getCallId()
      Gets the SIP call-id accociated with the message.

      Returns:
      the call-id

    • getChatRoom

      @NonNull ChatRoom getChatRoom()
      Returns the chatroom this message belongs to.

      Returns:
      the ChatRoom in which this message has been sent or received.

    • getContentType

      @NonNull String getContentType()
      Gets the content type of a chat message.

      Returns:
      The content type of the chat message

    • setContentType

      void setContentType(@NonNull String contentType)
      Sets the content type of a chat message.

      This content type must match a content that is text representable, such as
      text/plain, text/html or image/svg+xml.
      Parameters:
      contentType - The new content type of the chat message

    • getContents

      @NonNull Content[] getContents()
      Returns the list of contents in the message.

      Returns:
      The list of Content.

    • getCore

      @NonNull Core getCore()
      Returns back pointer to Core object.

      Returns:
      the Core object associated with this message.

    • getEphemeralExpireTime

      long getEphemeralExpireTime()
      Returns the real time at which an ephemeral message expires and will be
      deleted.

      see: isEphemeral()
      Returns:
      the time at which an ephemeral message expires. 0 means the message has
      not been read.

    • getEphemeralLifetime

      long getEphemeralLifetime()
      Returns lifetime of an ephemeral message.

      The lifetime is the duration after which the ephemeral message will disappear
      once viewed. see: isEphemeral()
      Returns:
      the lifetime of an ephemeral message, by default 0 (disabled).

    • getErrorInfo

      @NonNull ErrorInfo getErrorInfo()
      Gets full details about delivery error of a chat message.

      Returns:
      a ErrorInfo describing the details.

    • getExternalBodyUrl

      @Nullable String getExternalBodyUrl()
      Messages can carry external body as defined by rfc2017.

      Returns:
      external body url or null if not present.

    • setExternalBodyUrl

      void setExternalBodyUrl(@Nullable String externalBodyUrl)
      Messages can carry external body as defined by rfc2017.

      Parameters:
      externalBodyUrl - ex: access-type=URL; URL="http://www.foo.com/file"

    • getFileTransferInformation

      @Nullable Content getFileTransferInformation()
      Gets the file transfer information (used by callbacks to recover informations
      during a rcs file transfer)

      Returns:
      a pointer to the Content structure or null if not present.

    • getForwardInfo

      @Nullable String getForwardInfo()
      Gets the forward info if available as a string.

      Returns:
      the original sender of the message if it has been forwarded, null
      otherwise.

    • getFromAddress

      @NonNull Address getFromAddress()
      Gets origin of the message.

      Returns:
      the Address of the sender.

    • isEphemeral

      boolean isEphemeral()
      Returns wether the chat message is an ephemeral message or not.

      An ephemeral message will automatically disappear from the recipient's screen
      after the message has been viewed.
      Returns:
      true if it is an ephemeral message, false otherwise

    • isFileTransfer

      @Deprecated boolean isFileTransfer()
      Deprecated.
      06/07/2020 check if getContents() contains a Content
      for which Content.isFileTransfer() returns true.
      Return whether or not a chat message is a file transfer.

      Returns:
      Whether or not the message is a file transfer

    • isFileTransferInProgress

      boolean isFileTransferInProgress()
      Gets whether or not a file is currently being downloaded or uploaded.

      Returns:
      true if download or upload is in progress, false otherwise

    • isForward

      boolean isForward()
      Returns wether the chat message is a forward message or not.

      Returns:
      true if it is a forward message, false otherwise

    • isOutgoing

      boolean isOutgoing()
      Returns wehther the message has been sent or received.

      Returns:
      true if message has been sent, false if it has been received.

    • isRead

      boolean isRead()
      Returns wether the message has been read or not.

      Returns:
      true if message has been marked as read, false otherwise.

    • isReply

      boolean isReply()
      Returns wether the chat message is a reply message or not.

      Returns:
      true if it is a reply message, false otherwise

    • isSecured

      boolean isSecured()
      Gets if the message was end-to-end encrypted when transferred.

      Returns:
      true if the message was end-to-end encrypted when transferred, false
      otherwise.

    • isText

      @Deprecated boolean isText()
      Deprecated.
      06/07/2020 check if getContents() contains a Content
      with a PlainText content type.
      Return whether or not a chat message is a text.

      Returns:
      Whether or not the message is a text

    • getLocalAddress

      @NonNull Address getLocalAddress()
      Returns the local address the message was sent or received with.

      Returns:
      the Address of the local address used to send/receive this
      message.

    • getMessageId

      @NonNull String getMessageId()
      Get the message identifier.

      It is used to identify a message so that it can be notified as delivered and/or
      displayed.
      Returns:
      The message identifier.

    • getOwnReaction

      @Nullable ChatMessageReaction getOwnReaction()
      Returns our own reaction for a given chat message, if any.

      Returns:
      Our own ChatMessageReaction for that message if any, null
      otherwise.

    • getPeerAddress

      @NonNull Address getPeerAddress()
      Returns the peer (remote) address of the message.

      Returns:
      the Address of the peer address used to send/receive this
      message.

    • getReactions

      @NonNull ChatMessageReaction[] getReactions()
      Gets the list of reactions received for this chat message.

      Warning: list is ordered by content of reaction message, not by received
      timestamp!
      Returns:
      The sorted list of reaction if any.

    • getReplyMessage

      @Nullable ChatMessage getReplyMessage()
      Returns the ChatMessage this message is a reply to.

      Returns:
      the original message ChatMessage.

    • getReplyMessageId

      @Nullable String getReplyMessageId()
      Returns the ID of the message this is a reply to.

      Returns:
      the original message id.

    • getReplyMessageSenderAddress

      @Nullable Address getReplyMessageSenderAddress()
      Returns the address of the sender of the message this is a reply to.

      Returns:
      the original message sender Address.

    • getState

      ChatMessage.State getState()
      Gets the state of the message.

      Returns:
      the current ChatMessage.State of the message.

    • getTextContent

      @Deprecated @Nullable String getTextContent()
      Deprecated.
      01/07/2020. Use getUtf8Text() instead.
      Gets the text content if available as a string.

      Returns:
      the Content buffer if available in System Locale, null
      otherwise.

    • getTime

      long getTime()
      Gets the time the message was sent.

      Returns:
      the timestamp of when the message was sent.

    • getToAddress

      @NonNull Address getToAddress()
      Gets destination of the message.

      Returns:
      the Address of the recipient.

    • getToBeStored

      boolean getToBeStored()
      Gets if a chat message is to be stored.

      Returns:
      Whether or not the message is to be stored

    • setToBeStored

      void setToBeStored(boolean toBeStored)
      Sets if a chat message is to be stored.

      This content type must match a content that is text representable, such as
      text/plain, text/html or image/svg+xml.
      Parameters:
      toBeStored - Whether or not the chat message is to be stored

    • getUtf8Text

      @Nullable String getUtf8Text()
      Gets text part of this message.

      Returns:
      The text as UTF8 characters or null if no text.

    • setUtf8Text

      int setUtf8Text(@Nullable String text)
      Sets a text to be sent, given as a string of UTF-8 characters.

      Parameters:
      text - The text in UTF8 to set.
      Returns:
      0 if succeed.

    • addContent

      void addContent(@NonNull Content content)
      Adds a content to the ChatMessage.

      Parameters:
      content - the Content object to add.

    • addCustomHeader

      void addCustomHeader(@NonNull String headerName, @Nullable String headerValue)
      Adds custom headers to the message.

      Parameters:
      headerName - name of the header
      headerValue - header value

    • addFileContent

      void addFileContent(@NonNull Content content)
      Adds a file content to the ChatMessage.

      Parameters:
      content - the Content object to add.

    • addTextContent

      @Deprecated void addTextContent(@NonNull String text)
      Deprecated.
      01/07/2020. Use addUtf8TextContent(java.lang.String) instead.
      Creates a Content of type PlainText with the given text as body.

      Parameters:
      text - The text in System Locale to add to the message.

    • addUtf8TextContent

      void addUtf8TextContent(@NonNull String text)
      Creates a Content of type text/plain with the provided string, and
      attach it to the message.

      Parameters:
      text - The text to add to the message.

    • cancelFileTransfer

      void cancelFileTransfer()
      Cancels an ongoing file transfer attached to this message (upload or download).

    • createReaction

      @NonNull ChatMessageReaction createReaction(@NonNull String utf8Reaction)
      Creates a emoji reaction for the given chat mesage.

      To send it, use ChatMessageReaction.send().
      Parameters:
      utf8Reaction - the emoji character(s) as UTF-8.
      Returns:
      a ChatMessageReaction object.

    • downloadContent

      boolean downloadContent(@NonNull Content content)
      Starts the download of the Content referenced in the ChatMessage
      from remote server.

      Parameters:
      content - the Content object to download (must have the Content.isFileTransfer()
      method return true).
      Returns:
      false if there is an error, true otherwise.

    • downloadContents

      boolean downloadContents()
      Starts the download of all the Content objects representing file
      transfers included in the message (Content.isFileTransfer() method
      returns true).

      Returns:
      false if there is an error, true otherwise.

    • getCustomHeader

      @Nullable String getCustomHeader(@NonNull String headerName)
      Retrieves a custom header value given its name.

      Parameters:
      headerName - header name searched
      Returns:
      the custom header value or null if not found.

    • getParticipantsByImdnState

      @NonNull ParticipantImdnState[] getParticipantsByImdnState(ChatMessage.State state)
      Gets the list of participants for which the imdn state has reached the
      specified state and the time at which they did.

      Parameters:
      state - The LinphoneChatMessageState the imdn have reached (only use
      LinphoneChatMessageStateDelivered, LinphoneChatMessageStateDeliveredToUser,
      LinphoneChatMessageStateDisplayed and LinphoneChatMessageStateNotDelivered)
      Returns:
      The list of participants.

    • hasConferenceInvitationContent

      boolean hasConferenceInvitationContent()
      Returns wether the chat message has a conference invitation content or not.

      Returns:
      true if it has one, false otherwise.

    • hasTextContent

      @Deprecated boolean hasTextContent()
      Deprecated.
      27/10/2020. Check if getContents() contains a Content
      for which it's content type is PlainText.
      Returns wether the chat message has a text content or not.

      Returns:
      true if it has one, false otherwise.

    • markAsRead

      void markAsRead()
      Marks the message as read.

      Only triggers LinphoneChatRoomCbsChatRoomReadCb if it was the last unread
      message.

    • putChar

      int putChar(int character)
      Fulfills a chat message character by character and send the character
      immediately as real-time text (RFC4103 / T.140) or as Baudot tones.

      The method used to send the character depends on if real-time text is enabled
      or not. If it is, real-time text is of course used, otherwise Baudot will be
      used if it is enabled in the Core (see Core#enableBaudot). If
      real-time text is used, the ChatRoom the message was created from must
      be a real-time text capable chat room: it must be obtained by placing or
      receiving a call with real-time text capabilities (see CallParams#enableRealtimeText
      ), and getting the ChatRoom interface from the call with Call.getChatRoom()
      . When the message is terminated (ie a new line needs to be started), use
      send() in order to trigger the sending of the new line character and
      have the full message (comprising all characters sent so far) stored in local
      database.
      Parameters:
      character - The character to send (T.140 char for real-time text).
      Returns:
      0 if succeed.

    • removeContent

      void removeContent(@NonNull Content content)
      Removes a content from the ChatMessage.

      Parameters:
      content - the Content object to remove.

    • removeCustomHeader

      void removeCustomHeader(@NonNull String headerName)
      Removes a custom header from the message.

      Parameters:
      headerName - name of the header to remove

    • send

      void send()
      Sends a chat message.

    • addListener

      void addListener(ChatMessageListener listener)

    • removeListener

      void removeListener(ChatMessageListener listener)

    • setUserData

      void setUserData(Object data)
      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()
      Overrides:
      toString in class Object