Delta Chat Core C Interface
Public Member Functions | List of all members
dc_msg_t Class Reference

#include <deltachat.h>

Public Member Functions

uint32_t dc_msg_get_chat_id (const dc_msg_t *msg)
 Get the ID of chat the message belongs to. More...
 
int dc_msg_get_duration (const dc_msg_t *msg)
 Get the duration of audio or video. More...
 
uint32_t dc_msg_get_ephemeral_timer (const dc_msg_t *msg)
 Get ephemeral timer duration for message. More...
 
int64_t dc_msg_get_ephemeral_timestamp (const dc_msg_t *msg)
 Get timestamp of ephemeral message removal. More...
 
char * dc_msg_get_error (const dc_msg_t *msg)
 Gets the error status of the message. More...
 
char * dc_msg_get_file (const dc_msg_t *msg)
 Find out full path, file name and extension of the file associated with a message. More...
 
uint64_t dc_msg_get_filebytes (const dc_msg_t *msg)
 Get the size of the file. More...
 
char * dc_msg_get_filemime (const dc_msg_t *msg)
 Get mime type of the file. More...
 
char * dc_msg_get_filename (const dc_msg_t *msg)
 Get base file name without path. More...
 
uint32_t dc_msg_get_from_id (const dc_msg_t *msg)
 Get the ID of contact who wrote the message. More...
 
int dc_msg_get_height (const dc_msg_t *msg)
 Get height of image or video. More...
 
uint32_t dc_msg_get_id (const dc_msg_t *msg)
 Get the ID of the message. More...
 
int dc_msg_get_info_type (const dc_msg_t *msg)
 Get the type of an informational message. More...
 
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. More...
 
dc_msg_tdc_msg_get_quoted_msg (const dc_msg_t *msg)
 Get quoted message, if available. More...
 
char * dc_msg_get_quoted_text (const dc_msg_t *msg)
 Get quoted text, if any. More...
 
uint32_t dc_msg_get_real_chat_id (const dc_msg_t *msg)
 Get the ID of chat the message belongs to. More...
 
int64_t dc_msg_get_received_timestamp (const dc_msg_t *msg)
 Get message receive time. More...
 
char * dc_msg_get_setupcodebegin (const dc_msg_t *msg)
 Get the first characters of the setup code. More...
 
int dc_msg_get_showpadlock (const dc_msg_t *msg)
 Check if a padlock should be shown beside the message. More...
 
int64_t dc_msg_get_sort_timestamp (const dc_msg_t *msg)
 Get message time used for sorting. More...
 
int dc_msg_get_state (const dc_msg_t *msg)
 Get the state of a message. More...
 
char * dc_msg_get_subject (const dc_msg_t *msg)
 Get the subject of the email. More...
 
dc_lot_tdc_msg_get_summary (const dc_msg_t *msg, const dc_chat_t *chat)
 Get a summary for a message. More...
 
char * dc_msg_get_summarytext (const dc_msg_t *msg, int approx_characters)
 Get a message summary as a single line of text. More...
 
char * dc_msg_get_text (const dc_msg_t *msg)
 Get the text of the message. More...
 
int64_t dc_msg_get_timestamp (const dc_msg_t *msg)
 Get message sending time. More...
 
int dc_msg_get_videochat_type (const dc_msg_t *msg)
 Get type of videochat. More...
 
char * dc_msg_get_videochat_url (const dc_msg_t *msg)
 Get url of a videochat invitation. More...
 
int dc_msg_get_viewtype (const dc_msg_t *msg)
 Get the type of the message. More...
 
int dc_msg_get_width (const dc_msg_t *msg)
 Get width of image or video. More...
 
int dc_msg_has_deviating_timestamp (const dc_msg_t *msg)
 Check if a message has a deviating timestamp. More...
 
int dc_msg_has_html (dc_msg_t *msg)
 Checks if the message has a full HTML version. More...
 
int dc_msg_has_location (const dc_msg_t *msg)
 Check if a message has a location bound to it. More...
 
int dc_msg_is_bot (const dc_msg_t *msg)
 Check if incoming message is a bot message, i.e. More...
 
int dc_msg_is_forwarded (const dc_msg_t *msg)
 Check if the message is a forwarded message. More...
 
int dc_msg_is_increation (const dc_msg_t *msg)
 Check if a message is still in creation. More...
 
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. More...
 
int dc_msg_is_sent (const dc_msg_t *msg)
 Check if a message was sent successfully. More...
 
int dc_msg_is_setupmessage (const dc_msg_t *msg)
 Check if the message is an Autocrypt Setup Message. More...
 
void dc_msg_latefiling_mediasize (dc_msg_t *msg, int width, int height, int duration)
 Late filing information to a message. More...
 
dc_msg_tdc_msg_new (dc_context_t *context, int viewtype)
 Create new message object. More...
 
void dc_msg_set_dimension (dc_msg_t *msg, int width, int height)
 Set the dimensions associated with message object. More...
 
void dc_msg_set_duration (dc_msg_t *msg, int duration)
 Set the duration associated with message object. More...
 
void dc_msg_set_file (dc_msg_t *msg, const char *file, const char *filemime)
 Set the file associated with a message object. More...
 
void dc_msg_set_html (dc_msg_t *msg, const char *html)
 Set the HTML part of a message object. More...
 
void dc_msg_set_location (dc_msg_t *msg, double latitude, double longitude)
 Set any location that should be bound to the message object. More...
 
void dc_msg_set_override_sender_name (dc_msg_t *msg, const char *name)
 Set different sender name for a message. More...
 
void dc_msg_set_quote (dc_msg_t *msg, const dc_msg_t *quote)
 Set the message replying to. More...
 
void dc_msg_set_text (dc_msg_t *msg, const char *text)
 Set the text of a message object. More...
 
void dc_msg_unref (dc_msg_t *msg)
 Free a message object. More...
 

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_get_chat_id()

uint32_t dc_msg_get_chat_id ( const dc_msg_t msg)

Get the ID of chat the message belongs to.

To get details about the chat, pass the returned ID to dc_get_chat(). If a message is still in the deaddrop, the ID DC_CHAT_ID_DEADDROP is returned although internally another ID is used. (to get that internal id, use dc_msg_get_real_chat_id())

Parameters
msgThe message object.
Returns
The ID of the chat the message belongs to, 0 on errors.

◆ 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.

See also dc_msg_get_width() and dc_msg_get_height().

Parameters
msgThe message object.
Returns
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 ephemeral timer duration for 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
msgThe message object.
Returns
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 timestamp of 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
msgThe message object.
Returns
Time of 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
msgThe message object.
Returns
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, file name and extension of the file associated with a message.

Typically files are associated with images, videos, audios, documents. Plain text messages do not have a file.

Parameters
msgThe message object.
Returns
Full path, file name and extension of the file associated with the message. If there is no file associated with the message, an emtpy 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 messages, e.g. a PDF.

Parameters
msgThe message object.
Returns
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 mime type of the file.

If there is not 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
msgThe message object.
Returns
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 base file name without path.

The base file name includes the extension; the path is not returned. To get the full path, use dc_msg_get_file().

Parameters
msgThe message object.
Returns
Base file name plus extension without part. 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 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
msgThe 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 height of image or 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 ascpect ratio is the more interesting thing. You can calculate this using dc_msg_get_width() / dc_msg_get_height().

See also dc_msg_get_duration().

Parameters
msgThe message object.
Returns
Height in pixels, if applicable. 0 otherwise or if unknown.

◆ dc_msg_get_id()

uint32_t dc_msg_get_id ( const dc_msg_t msg)

Get the ID of the message.

Parameters
msgThe 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"

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

Parameters
msgThe 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 email 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
msgThe 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_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
msgThe 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
msgThe 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_real_chat_id()

uint32_t dc_msg_get_real_chat_id ( const dc_msg_t msg)

Get the ID of chat the message belongs to.

To get details about the chat, pass the returned ID to dc_get_chat(). In contrast to dc_msg_get_chat_id(), this function returns the chat-id also for messages in the deaddrop.

Parameters
msgThe message object.
Returns
The ID of the chat the message belongs to, 0 on errors.

◆ dc_msg_get_received_timestamp()

int64_t dc_msg_get_received_timestamp ( const dc_msg_t msg)

Get 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
msgThe message object.
Returns
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
msgThe 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
msgThe 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 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 reveived 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
msgThe message object.
Returns
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 (10) - 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 (13) - 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 (16) - 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 (18) - 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 (19) - Message saved as draft using dc_set_draft()
  • DC_STATE_OUT_PENDING (20) - 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 (24) - Unrecoverable error (recoverable errors result in pending messages), you'll receive the event DC_EVENT_MSG_FAILED.
  • DC_STATE_OUT_DELIVERED (26) - 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'll receive the event DC_EVENT_MSG_DELIVERED.
  • DC_STATE_OUT_MDN_RCVD (28) - 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'll 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 (0). 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
msgThe 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 email.

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
msgThe 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 (see dc_msg_get_state()).

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

Parameters
msgThe message object.
chatTo 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
msgThe message object.
approx_charactersRough 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
msgThe message object.
Returns
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 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
msgThe 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
msgThe message object.
Returns
Type of the videochat as of DC_VIDEOCHATTYPE_BASICWEBRTC, DC_VIDEOCHATTYPE_JITSI or DC_VIDEOCHATTYPE_UNKNOWN.

Example:

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
msgThe 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
msgThe message object.
Returns
One of the DC_MSG constants. 0 if the given message object is invalid.

◆ dc_msg_get_width()

int dc_msg_get_width ( const dc_msg_t msg)

Get width of image or 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().

See also dc_msg_get_duration().

Parameters
msgThe message object.
Returns
Width in pixels, if applicable. 0 otherwise or if unknown.

◆ 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
msgThe 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
msgThe message object.
Returns
0=Message as displayed using dc_msg_get_text() is just fine; 1=The 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
msgThe 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 incoming message is a bot message, i.e.

automatically submitted.

Return value for outgoing messages is unspecified.

Parameters
msgThe 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 email address of the original author (in a typical GUI, you select the messages text and click on "forwared"; 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
msgThe 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
msgThe 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(), dc_set_chat_protection() 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.

There is no need to perform any action when seeing such a message - this is already done by the core. Typically, these messages are displayed in the center of the chat.

Parameters
msgThe 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
msgThe 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
msgThe 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
msgThe message object.
widthThe new width to store in the message object. 0 if you do not want to change width and height.
heightThe new height to store in the message object. 0 if you do not want to change width and height.
durationThe new duration to store in the message object. 0 if you do not 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
contextThe context that should be stored in the message object.
viewtypeThe type to the message object to create, one of the DC_MSG constants.
Returns
The created message object.

◆ 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
msgThe message object.
widthWidth in pixels, if known. 0 if you don't know or don't care.
heightHeight 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
msgThe message object.
durationLength 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
msgThe message object.
fileIf the message object is used in dc_send_msg() later, this must be the full path of the image file to send.
filemimeMime 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 eg. for bots, that want to add rich content to a message, eg. 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
msgThe message object.
htmlHTML 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
msgThe message object.
latitudeNorth-south position of the location.
longitudeEast-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 eg. building bridges to other networks.

Parameters
msgThe message object.
nameThe 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
msgThe message object to set the reply to.
quoteThe quote to set for msg.

◆ 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
msgThe message object.
textMessage 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
msgThe message object to free. If NULL is given, nothing is done.

The documentation for this class was generated from the following file:
dc_msg_t::dc_msg_get_viewtype
int dc_msg_get_viewtype(const dc_msg_t *msg)
Get the type of the message.
dc_msg_t::dc_msg_get_videochat_type
int dc_msg_get_videochat_type(const dc_msg_t *msg)
Get type of videochat.
DC_MSG_VIDEOCHAT_INVITATION
#define DC_MSG_VIDEOCHAT_INVITATION
Message indicating an incoming or outgoing videochat.
Definition: deltachat.h:4539