Delta Chat Core C-API
Public Member Functions | List of all members
mrmsg_t Class Reference

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

#include <mrmsg.h>

Public Member Functions

void mrmsg_unref (mrmsg_t *msg)
 Free a message object. More...
 
uint32_t mrmsg_get_id (mrmsg_t *msg)
 Get the ID of the message. More...
 
uint32_t mrmsg_get_from_id (mrmsg_t *msg)
 Get the ID of contact who wrote the message. More...
 
uint32_t mrmsg_get_chat_id (mrmsg_t *msg)
 Get the ID of chat the message belongs to. More...
 
int mrmsg_get_type (mrmsg_t *msg)
 Get the type of the message. More...
 
int mrmsg_get_state (mrmsg_t *msg)
 Get the state of a message. More...
 
time_t mrmsg_get_timestamp (mrmsg_t *msg)
 Get message time. More...
 
char * mrmsg_get_text (mrmsg_t *msg)
 Get the text of the message. More...
 
char * mrmsg_get_file (mrmsg_t *msg)
 Find out full path, file name and extension of the file associated with a message. More...
 
char * mrmsg_get_filename (mrmsg_t *msg)
 Get base file name without path. More...
 
char * mrmsg_get_filemime (mrmsg_t *msg)
 Get mime type of the file. More...
 
uint64_t mrmsg_get_filebytes (mrmsg_t *msg)
 Get the size of the file. More...
 
mrlot_tmrmsg_get_mediainfo (mrmsg_t *msg)
 Get real author and title. More...
 
int mrmsg_get_width (mrmsg_t *msg)
 Get width of image or video. More...
 
int mrmsg_get_height (mrmsg_t *msg)
 Get height of image or video. More...
 
int mrmsg_get_duration (mrmsg_t *msg)
 Get duration of audio or video. More...
 
int mrmsg_get_showpadlock (mrmsg_t *msg)
 Check if a padlock should be shown beside the message. More...
 
mrlot_tmrmsg_get_summary (mrmsg_t *msg, mrchat_t *chat)
 Get a summary for a message. More...
 
char * mrmsg_get_summarytext (mrmsg_t *msg, int approx_characters)
 Get a message summary as a single line of text. More...
 
int mrmsg_is_sent (mrmsg_t *msg)
 Check if a message was sent successfully. More...
 
int mrmsg_is_starred (mrmsg_t *msg)
 Check if a message is starred. More...
 
int mrmsg_is_forwarded (mrmsg_t *msg)
 Check if the message is a forwarded message. More...
 
int mrmsg_is_systemcmd (mrmsg_t *msg)
 Check if the message is a system command. More...
 
int mrmsg_is_setupmessage (mrmsg_t *msg)
 Check if the message is an Autocrypt Setup Message. More...
 
char * mrmsg_get_setupcodebegin (mrmsg_t *msg)
 Get the first characters of the setup code. More...
 
int mrmsg_is_increation (mrmsg_t *msg)
 Check if a message is still in creation. More...
 
void mrmsg_latefiling_mediasize (mrmsg_t *msg, int width, int height, int duration)
 Late filing information to a message. 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

void mrmsg_unref ( mrmsg_t msg)

Free a message object.

Message objects are created eg. by mrmailbox_get_msg().

Parameters
msgThe message object to free.
Returns
None.
uint32_t mrmsg_get_id ( mrmsg_t msg)

Get the ID of the message.

Parameters
msgThe message object.
Returns
the ID of the message, 0 on errors.
uint32_t mrmsg_get_from_id ( mrmsg_t msg)

Get the ID of contact who wrote the message.

To get details about the contact, pass the returned ID to mrmailbox_get_contact().

Parameters
msgThe message object.
Returns
the ID of the contact who wrote the message, MR_CONTACT_ID_SELF (1) if this is an outgoing message, 0 on errors.
uint32_t mrmsg_get_chat_id ( mrmsg_t msg)

Get the ID of chat the message belongs to.

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

Parameters
msgThe message object.
Returns
the ID of the chat the message belongs to, 0 on errors.
int mrmsg_get_type ( mrmsg_t msg)

Get the type of the message.

Parameters
msgThe message object.
Returns
One of MR_MSG_TEXT (10), MR_MSG_IMAGE (20), MR_MSG_GIF (21), MR_MSG_AUDIO (40), MR_MSG_VOICE (41), MR_MSG_VIDEO (50), MR_MSG_FILE (60) or MR_MSG_UNDEFINED (0) if the type is undefined.
int mrmsg_get_state ( mrmsg_t msg)

Get the state of a message.

Incoming message states:

  • MR_STATE_IN_FRESH (10) - Incoming fresh message. Fresh messages are not noticed nor seen and are typically shown in notifications. Use mrmailbox_get_fresh_msgs() to get all fresh messages.
  • MR_STATE_IN_NOTICED (13) - Incoming noticed message. Eg. chat opened but message not yet read - noticed messages are not counted as unread but did not marked as read nor resulted in MDNs. Use mrmailbox_marknoticed_chat() or mrmailbox_marknoticed_contact() to mark messages as being noticed.
  • MR_STATE_IN_SEEN (16) - Incoming message, really seen by the user. Marked as read on IMAP and MDN may be send. Use mrmailbox_markseen_msgs() to mark messages as being seen.

Outgoing message states:

  • MR_STATE_OUT_PENDING (20) - The user has send the "send" button but the message is not yet sent and is pending in some way. Maybe we're offline (no checkmark).
  • MR_STATE_OUT_ERROR (24) - Unrecoverable error (recoverable errors result in pending messages)
  • MR_STATE_OUT_DELIVERED (26) - Outgoing message successfully delivered to server (one checkmark). Note, that already delivered messages may get into the state MR_STATE_OUT_ERROR if we get such a hint from the server. If a sent message changes to this state, you'll receive the event MR_EVENT_MSG_DELIVERED.
  • MR_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 MR_EVENT_MSG_READ.

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

The state of just created message objects is MR_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 eg. when calling mrmailbox_marknoticed_chat() or mrmailbox_markseen_msgs().

Parameters
msgThe message object.
Returns
The state of the message.
time_t mrmsg_get_timestamp ( mrmsg_t msg)

Get message time.

Unix time the message was sended or received.

Parameters
msgThe message object.
Returns
The time of the message.
char * mrmsg_get_text ( mrmsg_t msg)

Get the text of the message.

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

Parameters
msgThe message object.
Returns
Message text. The result must be free()'d. Never returns NULL.
char * mrmsg_get_file ( mrmsg_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 free()'d.
char * mrmsg_get_filename ( mrmsg_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 mrmsg_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 free()'d.
char * mrmsg_get_filemime ( mrmsg_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 free()'d after usage. NULL is never returned.
uint64_t mrmsg_get_filebytes ( mrmsg_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, eg. a PDF.

Parameters
msgThe message object.
Returns
File size in bytes, 0 if not applicable or on errors.
mrlot_t * mrmsg_get_mediainfo ( mrmsg_t msg)

Get real author and title.

The information is returned by a mrlot_t object with the following fields:

  • mrlot_t::m_text1: Author of the media. For voice messages, this is the sender. For music messages, the information are read from the filename. NULL if unknown.
  • mrlot_t::m_text2: Title of the media. For voice messages, this is the date. For music messages, the information are read from the filename. NULL if unknown.

Currently, we do not read ID3 and such at this stage, the needed libraries are too complicated and oversized. However, this is no big problem, as the sender usually sets the filename in a way we expect it.

Parameters
msgThe message object.
Returns
Media information as an mrlot_t object. Must be freed using mrlot_unref(). NULL is never returned.
int mrmsg_get_width ( mrmsg_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 ascpect ratio is the more interesting thing. You can calculate this using mrmsg_get_width() / mrmsg_get_height().

See also mrmsg_get_duration().

Parameters
msgThe message object.
Returns
Width in pixels, if applicable. 0 otherwise or if unknown.
int mrmsg_get_height ( mrmsg_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 mrmsg_get_width() / mrmsg_get_height().

See also mrmsg_get_duration().

Parameters
msgThe message object.
Returns
Height in pixels, if applicable. 0 otherwise or if unknown.
int mrmsg_get_duration ( mrmsg_t msg)

Get 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 mrmsg_get_width() and mrmsg_get_height().

Parameters
msgThe message object.
Returns
Duration in milliseconds, if applicable. 0 otherwise or if unknown.
int mrmsg_get_showpadlock ( mrmsg_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.
mrlot_t * mrmsg_get_summary ( mrmsg_t msg,
mrchat_t chat 
)

Get a summary for a message.

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

  • mrlot_t::m_text1: contains the username or the string "Me". The string may be colored by having a look at m_text1_meaning. If the name should not be displayed, the element is NULL.
  • mrlot_t::m_text1_meaning: one of MR_TEXT1_USERNAME or MR_TEXT1_SELF. Typically used to show mrlot_t::m_text1 with different colors. 0 if not applicable.
  • mrlot_t::m_text2: contains an excerpt of the message text.
  • mrlot_t::m_timestamp: the timestamp of the message.
  • mrlot_t::m_state: The state of the message as one of the MR_STATE_* constants (see mrmsg_get_state()).

Typically used to display a search result. See also mrchatlist_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 mrlot_t object. Must be freed using mrlot_unref(). NULL is never returned.
char * mrmsg_get_summarytext ( mrmsg_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 free()'d. Returns an empty string on errors, never returns NULL.
int mrmsg_is_sent ( mrmsg_t msg)

Check if a message was sent successfully.

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

Parameters
msgThe message object.
Returns
1=message sent successfully, 0=message not yet sent or message is an incoming message.
int mrmsg_is_starred ( mrmsg_t msg)

Check if a message is starred.

Starred messages are "favorites" marked by the user with a "star" or something like that. Starred messages can typically be shown easily and are not deleted automatically.

To star one or more messages, use mrmailbox_star_msgs(), to get a list of starred messages, use mrmailbox_get_chat_msgs() using MR_CHAT_ID_STARRED as the chat_id.

Parameters
msgThe message object.
Returns
1=message is starred, 0=message not starred.
int mrmsg_is_forwarded ( mrmsg_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.
int mrmsg_is_systemcmd ( mrmsg_t msg)

Check if the message is a system command.

System command messages are messages not "typed" by the user but created due to other actions, eg. mrmailbox_set_chat_name(), mrmailbox_set_chat_profile_image() or mrmailbox_add_contact_to_chat().

mrmsg_get_text() returns a descriptive text about what is going on.

There is no need to perfrom any action when seeing such a message - this is already done by the core. Typically, this text is displayed in another color or in another font than normal user messages.

Parameters
msgThe message object.
Returns
1=message is a system command, 0=normal message
int mrmsg_is_setupmessage ( mrmsg_t msg)

Check if the message is an Autocrypt Setup Message.

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

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

Parameters
msgThe message object.
Returns
1=message is a setup message, 0=no setup message. For setup messages, mrmsg_is_systemcmd() returns 1 and mrmsg_get_type() returns MR_MSG_FILE.
char * mrmsg_get_setupcodebegin ( mrmsg_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 mrmsg_is_setupmessage(). To decrypt a secret key from a setup message, use mrmailbox_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 free()'d when done.
int mrmsg_is_increation ( mrmsg_t msg)

Check if a message is still in creation.

The user can mark files as being in creation by simply creating a file <filename>.increation. If <filename> is created then, the user should just delete <filename>.increation.

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

Parameters
msgthe message object
Returns
1=message is still in creation (<filename>.increation exists), 0=message no longer in creation
void mrmsg_latefiling_mediasize ( mrmsg_t msg,
int  width,
int  height,
int  duration 
)

Late filing information to a message.

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 mrmsg_get_width(), mrmsg_get_height() or mrmsg_get_duration() do not provide the expected values.

To get the stored values later, use mrmsg_get_width(), mrmsg_get_height() or mrmsg_get_duration().

Parameters
msgThe message object.
widthThe new width to store in the message object. 0 if you do not want to change it.
heightThe new height to store in the message object. 0 if you do not want to change it.
durationThe new duration to store in the message object. 0 if you do not want to change it.
Returns
None.

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