Delta Chat Core C-API
|
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_t * | mrmsg_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_t * | mrmsg_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... | |
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.
void mrmsg_unref | ( | mrmsg_t * | msg | ) |
Free a message object.
Message objects are created eg. by mrmailbox_get_msg().
msg | The message object to free. |
uint32_t mrmsg_get_id | ( | mrmsg_t * | msg | ) |
Get the ID of the message.
msg | The message object. |
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().
msg | The message object. |
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(). If a message is still in the deaddrop, the ID MR_CHAT_ID_DEADDROP is returned although internally another ID is used.
msg | The message object. |
int mrmsg_get_type | ( | mrmsg_t * | msg | ) |
Get the type of the message.
msg | The message object. |
int mrmsg_get_state | ( | mrmsg_t * | msg | ) |
Get the state of a message.
Incoming message states:
Outgoing message states:
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().
msg | The message object. |
time_t mrmsg_get_timestamp | ( | mrmsg_t * | msg | ) |
Get message time.
Unix time the message was sended or received.
msg | The message object. |
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.
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 eg. 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 mrmailbox_get_msg_info().
msg | The message object. |
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.
msg | The message object. |
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().
msg | The message object. |
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.
msg | The message object. |
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.
msg | The message object. |
Get real author and title.
The information is returned by a mrlot_t object with the following fields:
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.
msg | The message object. |
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().
msg | The message object. |
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().
msg | The message object. |
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().
msg | The message object. |
int mrmsg_get_showpadlock | ( | mrmsg_t * | msg | ) |
Check if a padlock should be shown beside the message.
msg | The message object. |
Get a summary for a message.
The summary is returned by a mrlot_t object with the following fields:
Typically used to display a search result. See also mrchatlist_get_summary() to display a list of chats.
msg | The message object. |
chat | 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. |
char * mrmsg_get_summarytext | ( | mrmsg_t * | msg, |
int | approx_characters | ||
) |
Get a message summary as a single line of text.
Typically used for notifications.
msg | The message object. |
approx_characters | Rough length of the expected string. |
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().
msg | The message object. |
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.
msg | The message object. |
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)
msg | The message object. |
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.
msg | The message object. |
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.
msg | The message object. |
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().
msg | The message object. |
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.
msg | the message object |
<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().
msg | The message object. |
width | The new width to store in the message object. 0 if you do not want to change it. |
height | The new height to store in the message object. 0 if you do not want to change it. |
duration | The new duration to store in the message object. 0 if you do not want to change it. |