An object representing a single message in memory. More...

#include <deltachat.h>

Public Member Functions
void	dc_msg_force_plaintext (dc_msg_t *msg)
	Force the message to be sent in plain text.

uint32_t	dc_msg_get_chat_id (const dc_msg_t *msg)
	Get the ID of the chat the message belongs to.

int	dc_msg_get_download_state (const dc_msg_t *msg)
	Check if the message is completely downloaded or if some further action is needed.

int	dc_msg_get_duration (const dc_msg_t *msg)
	Get the duration of audio or video.

uint32_t	dc_msg_get_ephemeral_timer (const dc_msg_t *msg)
	Get the ephemeral timer duration for a message.

int64_t	dc_msg_get_ephemeral_timestamp (const dc_msg_t *msg)
	Get the timestamp of the ephemeral message removal.

char *	dc_msg_get_error (const dc_msg_t *msg)
	Gets the error status of the message.

char *	dc_msg_get_file (const dc_msg_t *msg)
	Find out full path of the file associated with a message.

uint64_t	dc_msg_get_filebytes (const dc_msg_t *msg)
	Get the size of the file.

char *	dc_msg_get_filemime (const dc_msg_t *msg)
	Get the MIME type of a file.

char *	dc_msg_get_filename (const dc_msg_t *msg)
	Get an original attachment filename, with extension but without the path.

uint32_t	dc_msg_get_from_id (const dc_msg_t *msg)
	Get the ID of the contact who wrote the message.

int	dc_msg_get_height (const dc_msg_t *msg)
	Get the height of an image or a video.

uint32_t	dc_msg_get_id (const dc_msg_t *msg)
	Get the ID of the message.

int	dc_msg_get_info_type (const dc_msg_t *msg)
	Get the type of an informational message.

char *	dc_msg_get_override_sender_name (const dc_msg_t *msg)
	Get the name that should be shown over the message (in a group chat) instead of the contact display name, or NULL.

dc_msg_t *	dc_msg_get_parent (const dc_msg_t *msg)
	Get parent message, if available.

dc_msg_t *	dc_msg_get_quoted_msg (const dc_msg_t *msg)
	Get quoted message, if available.

char *	dc_msg_get_quoted_text (const dc_msg_t *msg)
	Get quoted text, if any.

int64_t	dc_msg_get_received_timestamp (const dc_msg_t *msg)
	Get the message receive time.

char *	dc_msg_get_setupcodebegin (const dc_msg_t *msg)
	Get the first characters of the setup code.

int	dc_msg_get_showpadlock (const dc_msg_t *msg)
	Check if a padlock should be shown beside the message.

int64_t	dc_msg_get_sort_timestamp (const dc_msg_t *msg)
	Get the message time used for sorting.

int	dc_msg_get_state (const dc_msg_t *msg)
	Get the state of a message.

char *	dc_msg_get_subject (const dc_msg_t *msg)
	Get the subject of the e-mail.

dc_lot_t *	dc_msg_get_summary (const dc_msg_t msg, const dc_chat_t chat)
	Get a summary for a message.

char *	dc_msg_get_summarytext (const dc_msg_t *msg, int approx_characters)
	Get a message summary as a single line of text.

char *	dc_msg_get_text (const dc_msg_t *msg)
	Get the text of the message.

int64_t	dc_msg_get_timestamp (const dc_msg_t *msg)
	Get the message sending time.

int	dc_msg_get_videochat_type (const dc_msg_t *msg)
	Get type of videochat.

char *	dc_msg_get_videochat_url (const dc_msg_t *msg)
	Get URL of a videochat invitation.

int	dc_msg_get_viewtype (const dc_msg_t *msg)
	Get the type of the message.

char *	dc_msg_get_webxdc_blob (const dc_msg_t msg, const char filename, size_t *ret_bytes)
	Return a file from inside a webxdc message.

char *	dc_msg_get_webxdc_info (const dc_msg_t *msg)
	Get info from a webxdc message, in JSON format.

int	dc_msg_get_width (const dc_msg_t *msg)
	Get the width of an image or a video.

int	dc_msg_has_deviating_timestamp (const dc_msg_t *msg)
	Check if a message has a deviating timestamp.

int	dc_msg_has_html (dc_msg_t *msg)
	Checks if the message has a full HTML version.

int	dc_msg_has_location (const dc_msg_t *msg)
	Check if a message has a location bound to it.

int	dc_msg_is_bot (const dc_msg_t *msg)
	Check if an incoming message is a bot message, i.e.

int	dc_msg_is_forwarded (const dc_msg_t *msg)
	Check if the message is a forwarded message.

int	dc_msg_is_increation (const dc_msg_t *msg)
	Check if a message is still in creation.

int	dc_msg_is_info (const dc_msg_t *msg)
	Check if the message is an informational message, created by the device or by another users.

int	dc_msg_is_sent (const dc_msg_t *msg)
	Check if a message was sent successfully.

int	dc_msg_is_setupmessage (const dc_msg_t *msg)
	Check if the message is an Autocrypt Setup Message.

void	dc_msg_latefiling_mediasize (dc_msg_t *msg, int width, int height, int duration)
	Late filing information to a message.

dc_msg_t *	dc_msg_new (dc_context_t *context, int viewtype)
	Create new message object.

int	dc_msg_save_file (const dc_msg_t msg, const char path)
	Save file copy at the user-provided path.

void	dc_msg_set_dimension (dc_msg_t *msg, int width, int height)
	Set the dimensions associated with message object.

void	dc_msg_set_duration (dc_msg_t *msg, int duration)
	Set the duration associated with message object.

void	dc_msg_set_file (dc_msg_t msg, const char file, const char *filemime)
	Set the file associated with a message object.

void	dc_msg_set_html (dc_msg_t msg, const char html)
	Set the HTML part of a message object.

void	dc_msg_set_location (dc_msg_t *msg, double latitude, double longitude)
	Set any location that should be bound to the message object.

void	dc_msg_set_override_sender_name (dc_msg_t msg, const char name)
	Set different sender name for a message.

void	dc_msg_set_quote (dc_msg_t msg, const dc_msg_t quote)
	Set the message replying to.

void	dc_msg_set_subject (dc_msg_t msg, const char subject)
	Sets the email's subject.

void	dc_msg_set_text (dc_msg_t msg, const char text)
	Set the text of a message object.

void	dc_msg_unref (dc_msg_t *msg)
	Free a message object.

Detailed Description

An object representing a single message in memory.

The message object is not updated. If you want an update, you have to recreate the object.

Member Function Documentation

◆ dc_msg_force_plaintext()

void dc_msg_force_plaintext ( dc_msg_t * msg )

Force the message to be sent in plain text.

This API is for bots, there is no need to expose it in the UI.

Parameters

msg	The message object.

◆ dc_msg_get_chat_id()

uint32_t dc_msg_get_chat_id ( const dc_msg_t * msg )

Get the ID of the chat the message belongs to.

To get details about the chat, pass the returned ID to dc_get_chat().

Parameters

msg	The message object.

Returns: The ID of the chat the message belongs to, 0 on errors.

◆ dc_msg_get_download_state()

int dc_msg_get_download_state ( const dc_msg_t * msg )

Check if the message is completely downloaded or if some further action is needed.

Messages may be not fully downloaded if they are larger than the limit set by the dc_set_config()-option download_limit.

The function returns one of:

DC_DOWNLOAD_DONE - The message does not need any further download action and should be rendered as usual.
DC_DOWNLOAD_AVAILABLE - There is additional content to download. In addition to the usual message rendering, the UI shall show a download button that calls dc_download_full_msg()
DC_DOWNLOAD_IN_PROGRESS - Download was started with dc_download_full_msg() and is still in progress. If the download fails or succeeds, the event DC_EVENT_MSGS_CHANGED is emitted.
DC_DOWNLOAD_UNDECIPHERABLE - The message does not need any futher download action. It was fully downloaded, but we failed to decrypt it.
DC_DOWNLOAD_FAILURE - Download error, the user may start over calling dc_download_full_msg() again.

Parameters

msg	The message object.

Returns: One of the DC_DOWNLOAD values.

◆ dc_msg_get_duration()

int dc_msg_get_duration ( const dc_msg_t * msg )

Get the duration of audio or video.

The duration is returned in milliseconds (ms). If the duration is unknown or if the associated file is no audio or video file, 0 is returned.

Parameters

msg	The message object.

Returns: The duration in milliseconds, if applicable. 0 otherwise or if unknown.

◆ dc_msg_get_ephemeral_timer()

uint32_t dc_msg_get_ephemeral_timer ( const dc_msg_t * msg )

Get the ephemeral timer duration for a message.

This is the value of dc_get_chat_ephemeral_timer() in the moment the message was sent.

To check if the timer is started and calculate remaining time, use dc_msg_get_ephemeral_timestamp().

Parameters

msg	The message object.

Returns: The duration in seconds, or 0 if no timer is set.

◆ dc_msg_get_ephemeral_timestamp()

int64_t dc_msg_get_ephemeral_timestamp ( const dc_msg_t * msg )

Get the timestamp of the ephemeral message removal.

If returned value is non-zero, you can calculate the * fraction of time remaining by divinding the difference between the current timestamp and this timestamp by dc_msg_get_ephemeral_timer().

Parameters

msg	The message object.

Returns: The time of the message removal, 0 if the timer is not yet started. (The timer starts on sending messages or when dc_markseen_msgs() is called.)

◆ dc_msg_get_error()

char * dc_msg_get_error ( const dc_msg_t * msg )

Gets the error status of the message.

If there is no error associated with the message, NULL is returned.

A message can have an associated error status if something went wrong when sending or receiving message itself. The error status is free-form text and should not be further parsed, rather it's presence is meant to indicate something went wrong with the message and the text of the error is detailed information on what.

Some common reasons error can be associated with messages are:

Lack of valid signature on an e2ee message, usually for received messages.
Failure to decrypt an e2ee message, usually for received messages.
When a message could not be delivered to one or more recipients the non-delivery notification text can be stored in the error status.

Parameters

msg	The message object.

Returns: An error or NULL. The result must be released using dc_str_unref().

◆ dc_msg_get_file()

char * dc_msg_get_file ( const dc_msg_t * msg )

Find out full path of the file associated with a message.

Typically files are associated with images, videos, audios, documents. Plain text messages do not have a file. File name may be mangled. To obtain the original attachment filename use dc_msg_get_filename().

Parameters

msg	The message object.

Returns: The full path (with file name and extension) of the file associated with the message. If there is no file associated with the message, an empty string is returned. NULL is never returned and the returned value must be released using dc_str_unref().

◆ dc_msg_get_filebytes()

uint64_t dc_msg_get_filebytes ( const dc_msg_t * msg )

Get the size of the file.

Returns the size of the file associated with a message, if applicable.

Typically, this is used to show the size of document files, e.g. a PDF.

Parameters

msg	The message object.

Returns: The file size in bytes, 0 if not applicable or on errors.

◆ dc_msg_get_filemime()

char * dc_msg_get_filemime ( const dc_msg_t * msg )

Get the MIME type of a file.

If there is no file, an empty string is returned. If there is no associated MIME type with the file, the function guesses on; if in doubt, application/octet-stream is returned. NULL is never returned.

Parameters

msg	The message object.

Returns: A string containing the MIME type. Must be released using dc_str_unref() after usage. NULL is never returned.

◆ dc_msg_get_filename()

char * dc_msg_get_filename ( const dc_msg_t * msg )

Get an original attachment filename, with extension but without the path.

To get the full path, use dc_msg_get_file().

Parameters

msg	The message object.

Returns: The attachment filename. If there is no file associated with the message, an empty string is returned. The returned value must be released using dc_str_unref().

◆ dc_msg_get_from_id()

uint32_t dc_msg_get_from_id ( const dc_msg_t * msg )

Get the ID of the contact who wrote the message.

If the ID is equal to DC_CONTACT_ID_SELF (1), the message is an outgoing message that is typically shown on the right side of the chat view.

Otherwise, the message is an incoming message; to get details about the sender, pass the returned ID to dc_get_contact().

Parameters

msg	The message object.

Returns: The ID of the contact who wrote the message, DC_CONTACT_ID_SELF (1) if this is an outgoing message, 0 on errors.

◆ dc_msg_get_height()

int dc_msg_get_height ( const dc_msg_t * msg )

Get the height of an image or a video.

The height is returned in pixels. If the height is unknown or if the associated file is no image or video file, 0 is returned.

Often the aspect ratio is the more interesting thing. You can calculate this using dc_msg_get_width() / dc_msg_get_height().

◆ dc_msg_get_id()

uint32_t dc_msg_get_id ( const dc_msg_t * msg )

Get the ID of the message.

Parameters

msg	The message object.

Returns: The ID of the message. 0 if the given message object is invalid.

◆ dc_msg_get_info_type()

int dc_msg_get_info_type ( const dc_msg_t * msg )

Get the type of an informational message.

If dc_msg_is_info() returns 1, this function returns the type of the informational message. UIs can display e.g. an icon based upon the type.

Currently, the following types are defined:

DC_INFO_PROTECTION_ENABLED (11) - Info-message for "Chat is now protected"
DC_INFO_PROTECTION_DISABLED (12) - Info-message for "Chat is no longer protected"
DC_INFO_INVALID_UNENCRYPTED_MAIL (13) - Info-message for "Provider requires end-to-end encryption which is not setup yet", the UI should change the corresponding string using DC_STR_INVALID_UNENCRYPTED_MAIL and also offer a way to fix the encryption, eg. by a button offering a QR scan

Even when you display an icon, you should still display the text of the informational message using dc_msg_get_text()

Parameters

msg	The message object.

Returns: One of the DC_INFO* constants. 0 or other values indicate unspecified types or that the message is not an info-message.

◆ dc_msg_get_override_sender_name()

char * dc_msg_get_override_sender_name ( const dc_msg_t * msg )

Get the name that should be shown over the message (in a group chat) instead of the contact display name, or NULL.

If this returns non-NULL, put a ~ before the override-sender-name and show the override-sender-name and the sender's avatar even in 1:1 chats.

In mailing lists, sender display name and sender address do not always belong together. In this case, this function gives you the name that should actually be shown over the message.

Also, sometimes, we need to indicate a different sender in 1:1 chats: Suppose that our user writes an e-mail to suppo.nosp@m.rt@d.nosp@m.elta..nosp@m.chat, which forwards to Bob bob@d.nosp@m.elta.nosp@m..chat, and Bob replies.

Then, Bob's reply is shown in our 1:1 chat with suppo.nosp@m.rt@d.nosp@m.elta..nosp@m.chat and the override-sender-name is set to Bob. The UI should show the sender name as ~Bob and show the avatar, just as in group messages. If the user then taps on the avatar, they can see that this message comes from bob@d.nosp@m.elta.nosp@m..chat.

You should show a ~ before the override-sender-name in chats, so that the user can see that this isn't the sender's actual name.

Parameters

msg	The message object.

Returns: The name to show over this message or NULL. If this returns NULL, call dc_contact_get_display_name(). The returned string must be released using dc_str_unref().

◆ dc_msg_get_parent()

dc_msg_t * dc_msg_get_parent ( const dc_msg_t * msg )

Get parent message, if available.

Used for Webxdc-info-messages to jump to the corresponding instance that created the info message.

For quotes, please use the more specialized dc_msg_get_quoted_text() and dc_msg_get_quoted_msg().

Parameters

msg	The message object.

Returns: The parent message or NULL. Must be freed using dc_msg_unref() after usage.

◆ dc_msg_get_quoted_msg()

dc_msg_t * dc_msg_get_quoted_msg ( const dc_msg_t * msg )

Get quoted message, if available.

UIs might use this information to offer "jumping back" to the quoted message or to enrich displaying the quote.

If this function returns NULL, this does not mean there is no quote for the message - it might also mean that a quote exist but the quoted message is deleted meanwhile. Therefore, do not use this function to check if there is a quote for a message. To check if a message has a quote, use dc_msg_get_quoted_text().

To display the quote in the chat, use dc_msg_get_quoted_text() as a primary source, however, one might add information from the message object (e.g. an image).

It is not guaranteed that the message belong to the same chat.

Parameters

msg	The message object.

Returns: The quoted message or NULL. Must be freed using dc_msg_unref() after usage.

◆ dc_msg_get_quoted_text()

char * dc_msg_get_quoted_text ( const dc_msg_t * msg )

Get quoted text, if any.

You can use this function also check if there is a quote for a message.

The text is a summary of the original text, similar to what is shown in the chatlist.

If available, you can get the whole quoted message object using dc_msg_get_quoted_msg().

Parameters

msg	The message object.

Returns: The quoted text or NULL if there is no quote. Returned strings must be released using dc_str_unref().

◆ dc_msg_get_received_timestamp()

int64_t dc_msg_get_received_timestamp ( const dc_msg_t * msg )

Get the message receive time.

The receive time is returned as a unix timestamp in seconds.

To get the sending time, use dc_msg_get_timestamp().

Parameters

msg	The message object.

Returns: The receiving time of the message. For outgoing messages, 0 is returned.

◆ dc_msg_get_setupcodebegin()

char * dc_msg_get_setupcodebegin ( const dc_msg_t * msg )

Get the first characters of the setup code.

Typically, this is used to pre-fill the first entry field of the setup code. If the user has several setup messages, he can be sure typing in the correct digits.

To check, if a message is a setup message, use dc_msg_is_setupmessage(). To decrypt a secret key from a setup message, use dc_continue_key_transfer().

Parameters

msg	The message object.

Returns: Typically the first two digits of the setup code or an empty string if unknown. NULL is never returned. Must be released using dc_str_unref() when done.

◆ dc_msg_get_showpadlock()

int dc_msg_get_showpadlock ( const dc_msg_t * msg )

Check if a padlock should be shown beside the message.

Parameters

msg	The message object.

Returns: 1=padlock should be shown beside message, 0=do not show a padlock beside the message.

◆ dc_msg_get_sort_timestamp()

int64_t dc_msg_get_sort_timestamp ( const dc_msg_t * msg )

Get the message time used for sorting.

This function returns the timestamp that is used for sorting the message into lists as returned e.g. by dc_get_chat_msgs(). This may be the received time, the sending time or another time.

To get the receiving time, use dc_msg_get_received_timestamp(). To get the sending time, use dc_msg_get_timestamp().

Parameters

msg	The message object.

Returns: The time used for ordering.

◆ dc_msg_get_state()

int dc_msg_get_state ( const dc_msg_t * msg )

Get the state of a message.

Incoming message states:

DC_STATE_IN_FRESH - Incoming fresh message. Fresh messages are neither noticed nor seen and are typically shown in notifications. Use dc_get_fresh_msgs() to get all fresh messages.
DC_STATE_IN_NOTICED - Incoming noticed message. E.g. chat opened but message not yet read. Noticed messages are not counted as unread but were not marked as read nor resulted in MDNs. Use dc_marknoticed_chat() to mark messages as being noticed.
DC_STATE_IN_SEEN - Incoming message, really seen by the user. Marked as read on IMAP and MDN may be sent. Use dc_markseen_msgs() to mark messages as being seen.

Outgoing message states:

DC_STATE_OUT_PREPARING - For files which need time to be prepared before they can be sent, the message enters this state before DC_STATE_OUT_PENDING.
DC_STATE_OUT_DRAFT - Message saved as draft using dc_set_draft()
DC_STATE_OUT_PENDING - The user has pressed the "send" button but the message is not yet sent and is pending in some way. Maybe we're offline (no checkmark).
DC_STATE_OUT_FAILED - Unrecoverable error (recoverable errors result in pending messages), you will receive the event DC_EVENT_MSG_FAILED.
DC_STATE_OUT_DELIVERED - Outgoing message successfully delivered to server (one checkmark). Note, that already delivered messages may get into the state DC_STATE_OUT_FAILED if we get such a hint from the server. If a sent message changes to this state, you will receive the event DC_EVENT_MSG_DELIVERED.
DC_STATE_OUT_MDN_RCVD - Outgoing message read by the recipient (two checkmarks; this requires goodwill on the receiver's side) If a sent message changes to this state, you will receive the event DC_EVENT_MSG_READ. Also messages already read by some recipients may get into the state DC_STATE_OUT_FAILED at a later point, e.g. when in a group, delivery fails for some recipients.

If you just want to check if a message is sent or not, please use dc_msg_is_sent() which regards all states accordingly.

The state of just created message objects is DC_STATE_UNDEFINED. The state is always set by the core library, users of the library cannot set the state directly, but it is changed implicitly e.g. when calling dc_marknoticed_chat() or dc_markseen_msgs().

Parameters

msg	The message object.

Returns: The state of the message.

◆ dc_msg_get_subject()

char * dc_msg_get_subject ( const dc_msg_t * msg )

Get the subject of the e-mail.

If there is no subject associated with the message, an empty string is returned. NULL is never returned.

You usually don't need this; if the core thinks that the subject might contain important information, it automatically prepends it to the message text.

This function was introduced so that you can use the subject as the title for the full-message-view (see dc_get_msg_html()).

For outgoing messages, the subject is not stored and an empty string is returned.

Parameters

msg	The message object.

Returns: The subject. The result must be released using dc_str_unref(). Never returns NULL.

◆ dc_msg_get_summary()

dc_lot_t * dc_msg_get_summary	(	const dc_msg_t *	msg,
		const dc_chat_t *	chat )

Get a summary for a message.

The summary is returned by a dc_lot_t object with the following fields:

dc_lot_t::text1: contains the username or the string "Me". The string may be colored by having a look at text1_meaning. If the name should not be displayed, the element is NULL.
dc_lot_t::text1_meaning: one of DC_TEXT1_USERNAME or DC_TEXT1_SELF. Typically used to show dc_lot_t::text1 with different colors. 0 if not applicable.
dc_lot_t::text2: contains an excerpt of the message text.
dc_lot_t::timestamp: the timestamp of the message.
dc_lot_t::state: The state of the message as one of the DC_STATE constants.

Typically used to display a search result. See also dc_chatlist_get_summary() to display a list of chats.

Parameters

msg	The message object.
chat	The chat object. To speed up things, pass an already available chat object here. If the chat object is not yet available, it is faster to pass NULL.

Returns: The summary as an dc_lot_t object. Must be freed using dc_lot_unref(). NULL is never returned.

◆ dc_msg_get_summarytext()

char * dc_msg_get_summarytext	(	const dc_msg_t *	msg,
		int	approx_characters )

Get a message summary as a single line of text.

Typically used for notifications.

Parameters

msg	The message object.
approx_characters	A rough length of the expected string.

Returns: A summary for the given messages. The returned string must be released using dc_str_unref(). Returns an empty string on errors, never returns NULL.

◆ dc_msg_get_text()

char * dc_msg_get_text ( const dc_msg_t * msg )

Get the text of the message.

If there is no text associated with the message, an empty string is returned. NULL is never returned.

The returned text is plain text, HTML is stripped. The returned text is truncated to a max. length of currently about 30000 characters, it does not make sense to show more text in the message list and typical controls will have problems with showing much more text. This max. length is to avoid passing lots of data to the frontend which may result e.g. from decoding errors (assume some bytes missing in a mime structure, forcing an attachment to be plain text).

To get information about the message and more/raw text, use dc_get_msg_info().

Parameters

msg	The message object.

Returns: The message text. The result must be released using dc_str_unref(). Never returns NULL.

◆ dc_msg_get_timestamp()

int64_t dc_msg_get_timestamp ( const dc_msg_t * msg )

Get the message sending time.

The sending time is returned as a unix timestamp in seconds.

Note that the message lists returned e.g. by dc_get_chat_msgs() are not sorted by the sending time but by the receiving time. This ensures newly received messages always pop up at the end of the list, however, for delayed messages, the correct sending time will be displayed.

To display detailed information about the times to the user, the UI can use dc_get_msg_info().

Parameters

msg	The message object.

Returns: The time of the message.

◆ dc_msg_get_videochat_type()

int dc_msg_get_videochat_type ( const dc_msg_t * msg )

Get type of videochat.

Calling this functions only makes sense for messages of type DC_MSG_VIDEOCHAT_INVITATION, in this case, if basicwebrtc: as of https://github.com/cracker0dks/basicwebrtc or jitsi were used to initiate the videochat, dc_msg_get_videochat_type() returns the corresponding type.

The videochat URL can be retrieved using dc_msg_get_videochat_url(). To check if a message is a videochat invitation at all, check the message type for DC_MSG_VIDEOCHAT_INVITATION.

Parameters

msg	The message object.

Returns: Type of the videochat as of DC_VIDEOCHATTYPE_BASICWEBRTC, DC_VIDEOCHATTYPE_JITSI or DC_VIDEOCHATTYPE_UNKNOWN.

Example:

if (dc_msg_get_viewtype(msg) == DC_MSG_VIDEOCHAT_INVITATION) {
  if (dc_msg_get_videochat_type(msg) == DC_VIDEOCHATTYPE_BASICWEBRTC) {
      // videochat invitation that we ship a client for
  } else {
      // use browser for videochat - or add an additional check for DC_VIDEOCHATTYPE_JITSI
  }
} else {
   // not a videochat invitation
}

◆ dc_msg_get_videochat_url()

char * dc_msg_get_videochat_url ( const dc_msg_t * msg )

Get URL of a videochat invitation.

Videochat invitations are sent out using dc_send_videochat_invitation() and dc_msg_get_viewtype() returns DC_MSG_VIDEOCHAT_INVITATION for such invitations.

Parameters

msg	The message object.

Returns: If the message contains a videochat invitation, the URL of the invitation is returned. If the message is no videochat invitation, NULL is returned. Must be released using dc_str_unref() when done.

◆ dc_msg_get_viewtype()

int dc_msg_get_viewtype ( const dc_msg_t * msg )

Get the type of the message.

Parameters

msg	The message object.

Returns: One of the DC_MSG constants. 0 if the given message object is invalid.

◆ dc_msg_get_webxdc_blob()

char * dc_msg_get_webxdc_blob	(	const dc_msg_t *	msg,
		const char *	filename,
		size_t *	ret_bytes )

Return a file from inside a webxdc message.

Parameters

msg	The webxdc instance.
filename	The name inside the archive. Can be given as an absolute path (`/file.png`) or as a relative path (`file.png`, no leading slash).
ret_bytes	A pointer to a size_t. The size of the blob will be written here.

Returns: The blob must be released using dc_str_unref() after usage. NULL if there is no such file in the archive or on errors.

◆ dc_msg_get_webxdc_info()

char * dc_msg_get_webxdc_info ( const dc_msg_t * msg )

Get info from a webxdc message, in JSON format.

The returned JSON string has the following key/values:

name: The name of the app. Defaults to the filename if not set in the manifest.
icon: App icon file name. Defaults to an standard icon if nothing is set in the manifest. To get the file, use dc_msg_get_webxdc_blob(). App icons should should be square, the implementations will add round corners etc. as needed.
document: if the Webxdc represents a document, this is the name of the document, otherwise, this is an empty string.
summary: short string describing the state of the app, sth. as "2 votes", "Highscore: 123", can be changed by the apps and defaults to an empty string.
source_code_url: URL where the source code of the Webxdc and other information can be found; defaults to an empty string. Implementations may offer an menu or a button to open this URL.
internet_access: true if the Webxdc should get full internet access, including Webrtc. currently, this is only true for encrypted Webxdc's in the self chat that have requested internet access in the manifest.

Parameters

msg	The webxdc instance.

Returns: A UTF8 encoded JSON string containing all requested info. Must be freed using dc_str_unref(). NULL is never returned.

◆ dc_msg_get_width()

int dc_msg_get_width ( const dc_msg_t * msg )

Get the width of an image or a video.

The width is returned in pixels. If the width is unknown or if the associated file is no image or video file, 0 is returned.

Often the aspect ratio is the more interesting thing. You can calculate this using dc_msg_get_width() / dc_msg_get_height().

◆ dc_msg_has_deviating_timestamp()

int dc_msg_has_deviating_timestamp ( const dc_msg_t * msg )

Check if a message has a deviating timestamp.

A message has a deviating timestamp when it is sent on another day as received/sorted by.

When the UI displays normally only the time beside the message and the full day as headlines, the UI should display the full date directly beside the message if the timestamp is deviating.

Parameters

msg	The message object.

Returns: 1=Timestamp is deviating, the UI should display the full date beside the message, 0=Timestamp is not deviating and belongs to the same date as the date headers, displaying the time only is sufficient in this case.

◆ dc_msg_has_html()

int dc_msg_has_html ( dc_msg_t * msg )

Checks if the message has a full HTML version.

Messages have a full HTML version if the original message may contain important parts that are removed by some heuristics or if the message is just too long or too complex to get displayed properly by just using plain text. If so, the UI should offer a button as "Show full message" that shows the uncut message using dc_get_msg_html().

Even if a "Show full message" button is recommended, the UI should display the text in the bubble using the normal dc_msg_get_text() function - which will still be fine in many cases.

Parameters

msg	The message object.

Returns: 0=Message as displayed using dc_msg_get_text() is just fine; 1=Message has a full HTML version, should be displayed using dc_msg_get_text() and a button to show the full version should be offered

◆ dc_msg_has_location()

int dc_msg_has_location ( const dc_msg_t * msg )

Check if a message has a location bound to it.

These messages are also returned by dc_get_locations() and the UI may decide to display a special icon beside such messages,

Parameters

msg	The message object.

Returns: 1=Message has location bound to it, 0=No location bound to message.

◆ dc_msg_is_bot()

int dc_msg_is_bot ( const dc_msg_t * msg )

Check if an incoming message is a bot message, i.e.

automatically submitted.

Return value for outgoing messages is unspecified.

Parameters

msg	The message object.

Returns: 1=message is submitted automatically, 0=message is not automatically submitted.

◆ dc_msg_is_forwarded()

int dc_msg_is_forwarded ( const dc_msg_t * msg )

Check if the message is a forwarded message.

Forwarded messages may not be created by the contact given as "from".

Typically, the UI shows a little text for a symbol above forwarded messages.

For privacy reasons, we do not provide the name or the e-mail address of the original author (in a typical GUI, you select the messages text and click on "forwarded"; you won't expect other data to be send to the new recipient, esp. as the new recipient may not be in any relationship to the original author)

Parameters

msg	The message object.

Returns: 1=message is a forwarded message, 0=message not forwarded.

◆ dc_msg_is_increation()

int dc_msg_is_increation ( const dc_msg_t * msg )

Check if a message is still in creation.

A message is in creation between the calls to dc_prepare_msg() and dc_send_msg().

Typically, this is used for videos that are recoded by the UI before they can be sent.

Parameters

msg	The message object.

Returns: 1=message is still in creation (dc_send_msg() was not called yet), 0=message no longer in creation.

◆ dc_msg_is_info()

int dc_msg_is_info ( const dc_msg_t * msg )

Check if the message is an informational message, created by the device or by another users.

Such messages are not "typed" by the user but created due to other actions, e.g. dc_set_chat_name(), dc_set_chat_profile_image(), or dc_add_contact_to_chat().

These messages are typically shown in the center of the chat view, dc_msg_get_text() returns a descriptive text about what is going on.

For informational messages created by Webxdc apps, dc_msg_get_parent() usually returns the Webxdc instance; UIs can use that to scroll to the Webxdc app when the info is tapped.

There is no need to perform any action when seeing such a message - this is already done by the core.

Parameters

msg	The message object.

Returns: 1=message is a system command, 0=normal message.

◆ dc_msg_is_sent()

int dc_msg_is_sent ( const dc_msg_t * msg )

Check if a message was sent successfully.

Currently, "sent" messages are messages that are in the state "delivered" or "mdn received", see dc_msg_get_state().

Parameters

msg	The message object.

Returns: 1=message sent successfully, 0=message not yet sent or message is an incoming message.

◆ dc_msg_is_setupmessage()

int dc_msg_is_setupmessage ( const dc_msg_t * msg )

Check if the message is an Autocrypt Setup Message.

Setup messages should be shown in an unique way e.g. using a different text color. On a click or another action, the user should be prompted for the setup code which is forwarded to dc_continue_key_transfer() then.

Setup message are typically generated by dc_initiate_key_transfer() on another device.

Parameters

msg	The message object.

Returns: 1=message is a setup message, 0=no setup message. For setup messages, dc_msg_get_viewtype() returns DC_MSG_FILE.

◆ dc_msg_latefiling_mediasize()

void dc_msg_latefiling_mediasize	(	dc_msg_t *	msg,
		int	width,
		int	height,
		int	duration )

Late filing information to a message.

In contrast to the dc_msg_set_*() functions, this function really stores the information in the database.

Sometimes, the core cannot find out the width, the height or the duration of an image, an audio or a video.

If, in these cases, the frontend can provide the information, it can save them together with the message object for later usage.

This function should only be used if dc_msg_get_width(), dc_msg_get_height() or dc_msg_get_duration() do not provide the expected values.

To get the stored values later, use dc_msg_get_width(), dc_msg_get_height() or dc_msg_get_duration().

Parameters

msg	The message object.
width	The new width to store in the message object. 0 if you don't want to change the width.
height	The new height to store in the message object. 0 if you don't want to change the height.
duration	The new duration to store in the message object. 0 if you don't want to change it.

◆ dc_msg_new()

dc_msg_t * dc_msg_new	(	dc_context_t *	context,
		int	viewtype )

Create new message object.

Message objects are needed e.g. for sending messages using dc_send_msg(). Moreover, they are returned e.g. from dc_get_msg(), set up with the current state of a message. The message object is not updated; to achieve this, you have to recreate it.

Parameters

context	The context that should be stored in the message object.
viewtype	The type to the message object to create, one of the DC_MSG constants.

Returns: The created message object.

◆ dc_msg_save_file()

int dc_msg_save_file	(	const dc_msg_t *	msg,
		const char *	path )

Save file copy at the user-provided path.

Fails if file already exists at the provided path.

Parameters

msg	The message object.
path	Destination file path with filename and extension.

Returns: 0 on failure, 1 on success.

◆ dc_msg_set_dimension()

void dc_msg_set_dimension	(	dc_msg_t *	msg,
		int	width,
		int	height )

Set the dimensions associated with message object.

Typically this is the width and the height of an image or video associated using dc_msg_set_file(). This does not alter any information in the database; this may be done by dc_send_msg() later.

Parameters

msg	The message object.
width	The width in pixels, if known. 0 if you don't know or don't care.
height	The height in pixels, if known. 0 if you don't know or don't care.

◆ dc_msg_set_duration()

void dc_msg_set_duration	(	dc_msg_t *	msg,
		int	duration )

Set the duration associated with message object.

Typically this is the duration of an audio or video associated using dc_msg_set_file(). This does not alter any information in the database; this may be done by dc_send_msg() later.

Parameters

msg	The message object.
duration	The duration in milliseconds. 0 if you don't know or don't care.

◆ dc_msg_set_file()

void dc_msg_set_file	(	dc_msg_t *	msg,
		const char *	file,
		const char *	filemime )

Set the file associated with a message object.

This does not alter any information in the database nor copy or move the file or checks if the file exist. All this can be done with dc_send_msg() later.

Parameters

msg	The message object.
file	If the message object is used in dc_send_msg() later, this must be the full path of the image file to send.
filemime	The MIME type of the file. NULL if you don't know or don't care.

◆ dc_msg_set_html()

void dc_msg_set_html	(	dc_msg_t *	msg,
		const char *	html )

Set the HTML part of a message object.

As for all other dc_msg_t setters, this is only useful if the message is sent using dc_send_msg() later.

Please note, that Delta Chat clients show the plain text set with dc_msg_set_text() at the first place; the HTML part is not shown instead of this text. However, for messages with HTML parts, on the receiver's device, dc_msg_has_html() will return 1 and a button "Show full message" is typically shown.

So adding a HTML part might be useful e.g. for bots, that want to add rich content to a message, e.g. a website; this HTML part is similar to an attachment then.

dc_msg_set_html() is currently not meant for sending a message, a "normal user" has typed in! Use dc_msg_set_text() for that purpose.

Parameters

msg	The message object.
html	HTML to send.

◆ dc_msg_set_location()

void dc_msg_set_location	(	dc_msg_t *	msg,
		double	latitude,
		double	longitude )

Set any location that should be bound to the message object.

The function is useful to add a marker to the map at a position different from the self-location. You should not call this function if you want to bind the current self-location to a message; this is done by dc_set_location() and dc_send_locations_to_chat().

Typically results in the event DC_EVENT_LOCATION_CHANGED with contact ID set to DC_CONTACT_ID_SELF.

Parameters

msg	The message object.
latitude	A north-south position of the location.
longitude	An east-west position of the location.

◆ dc_msg_set_override_sender_name()

void dc_msg_set_override_sender_name	(	dc_msg_t *	msg,
		const char *	name )

Set different sender name for a message.

This overrides the name set by the dc_set_config()-option displayname.

Usually, this function is not needed when implementing pure messaging functions. However, it might be useful for bots e.g. building bridges to other networks.

Parameters

msg	The message object.
name	The name to send along with the message.

◆ dc_msg_set_quote()

void dc_msg_set_quote	(	dc_msg_t *	msg,
		const dc_msg_t *	quote )

Set the message replying to.

This allows optionally to reply to an explicit message instead of replying implicitly to the end of the chat.

dc_msg_set_quote() copies some basic data from the quoted message object so that dc_msg_get_quoted_text() will always work. dc_msg_get_quoted_msg() gets back the quoted message only if it is not deleted.

Parameters

msg	The message object to set the reply to.
quote	The quote to set for the message object given as `msg`. NULL removes an previously set quote.

◆ dc_msg_set_subject()

void dc_msg_set_subject	(	dc_msg_t *	msg,
		const char *	subject )

Sets the email's subject.

If it's empty, a default subject will be used (e.g. Message from Alice or Re: <last subject>). This does not alter any information in the database.

Parameters

msg	The message object.
subject	The new subject.

◆ dc_msg_set_text()

void dc_msg_set_text	(	dc_msg_t *	msg,
		const char *	text )

Set the text of a message object.

This does not alter any information in the database; this may be done by dc_send_msg() later.

Parameters

msg	The message object.
text	The message text.

◆ dc_msg_unref()

void dc_msg_unref ( dc_msg_t * msg )

Free a message object.

Message objects are created e.g. by dc_get_msg().

Parameters

msg	The message object to free. If NULL is given, nothing is done.

The documentation for this class was generated from the following file:

deltachat.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ dc_msg_force_plaintext()

◆ dc_msg_get_chat_id()

◆ dc_msg_get_download_state()

◆ dc_msg_get_duration()

◆ dc_msg_get_ephemeral_timer()

◆ dc_msg_get_ephemeral_timestamp()

◆ dc_msg_get_error()

◆ dc_msg_get_file()

◆ dc_msg_get_filebytes()

◆ dc_msg_get_filemime()

◆ dc_msg_get_filename()

◆ dc_msg_get_from_id()

◆ dc_msg_get_height()

◆ dc_msg_get_id()

◆ dc_msg_get_info_type()

◆ dc_msg_get_override_sender_name()

◆ dc_msg_get_parent()

◆ dc_msg_get_quoted_msg()

◆ dc_msg_get_quoted_text()

◆ dc_msg_get_received_timestamp()

◆ dc_msg_get_setupcodebegin()

◆ dc_msg_get_showpadlock()

◆ dc_msg_get_sort_timestamp()

◆ dc_msg_get_state()

◆ dc_msg_get_subject()

◆ dc_msg_get_summary()

◆ dc_msg_get_summarytext()

◆ dc_msg_get_text()

◆ dc_msg_get_timestamp()

◆ dc_msg_get_videochat_type()

◆ dc_msg_get_videochat_url()

◆ dc_msg_get_viewtype()

◆ dc_msg_get_webxdc_blob()

◆ dc_msg_get_webxdc_info()

◆ dc_msg_get_width()

◆ dc_msg_has_deviating_timestamp()

◆ dc_msg_has_html()

◆ dc_msg_has_location()

◆ dc_msg_is_bot()

◆ dc_msg_is_forwarded()

◆ dc_msg_is_increation()

◆ dc_msg_is_info()

◆ dc_msg_is_sent()

◆ dc_msg_is_setupmessage()

◆ dc_msg_latefiling_mediasize()

◆ dc_msg_new()

◆ dc_msg_save_file()

◆ dc_msg_set_dimension()

◆ dc_msg_set_duration()

◆ dc_msg_set_file()

◆ dc_msg_set_html()

◆ dc_msg_set_location()

◆ dc_msg_set_override_sender_name()

◆ dc_msg_set_quote()

◆ dc_msg_set_subject()

◆ dc_msg_set_text()

◆ dc_msg_unref()