![]() |
Delta Chat Core C-API
|
An object representing a single message in memory. More...
#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... | |
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... | |
time_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... | |
time_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... | |
dc_lot_t * | dc_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... | |
time_t | dc_msg_get_timestamp (const dc_msg_t *msg) |
Get message sending time. 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_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... | |
int | dc_msg_is_starred (const dc_msg_t *msg) |
Check if a message is starred. 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_t * | dc_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_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... | |
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.
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.
msg | The message object. |
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().
msg | The message object. |
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.
msg | The message object. |
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, eg. a PDF.
msg | The message object. |
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.
msg | The message object. |
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().
msg | The message object. |
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().
msg | The message object. |
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().
msg | The message object. |
uint32_t dc_msg_get_id | ( | const dc_msg_t * | msg | ) |
Get the ID of the message.
msg | The message object. |
time_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().
msg | The message object. |
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().
msg | The message object. |
int dc_msg_get_showpadlock | ( | const dc_msg_t * | msg | ) |
Check if a padlock should be shown beside the message.
msg | The message object. |
time_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 eg. 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().
msg | The message object. |
int dc_msg_get_state | ( | const dc_msg_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 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 eg. when calling dc_marknoticed_chat() or dc_markseen_msgs().
msg | The message object. |
Get a summary for a message.
The summary is returned by a dc_lot_t object with the following fields:
Typically used to display a search result. See also dc_chatlist_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 * 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.
msg | The message object. |
approx_characters | Rough length of the expected string. |
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 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 dc_get_msg_info().
msg | The message object. |
time_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 eg. 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().
msg | The message object. |
int dc_msg_get_viewtype | ( | const dc_msg_t * | msg | ) |
Get the type of the message.
msg | The message object. |
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().
msg | The message object. |
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.
msg | The message object. |
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)
msg | The message object. |
int dc_msg_is_increation | ( | const dc_msg_t * | msg | ) |
Check if a message is still in creation.
The UI can mark files as being in creation by simply creating a file <filename>.increation
. If <filename>
is created completely then, the user should just delete <filename>.increation
.
Typically, this is used for videos that are recoded by the UI before they can be sent.
msg | The message object |
<filename>.increation
exists), 0=message no longer 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.
Such messages are not "typed" by the user but created due to other actions, eg. 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.
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.
msg | The message object. |
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().
msg | The message object. |
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 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 dc_continue_key_transfer() then.
Setup message are typically generated by dc_initiate_key_transfer() on another device.
msg | The message object. |
int dc_msg_is_starred | ( | const dc_msg_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 dc_star_msgs(), to get a list of starred messages, use dc_get_chat_msgs() using DC_CHAT_ID_STARRED as the chat_id.
msg | The message object. |
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().
msg | The message object. |
width | The new width to store in the message object. 0 if you do not want to change width and height. |
height | The new height to store in the message object. 0 if you do not want to change width and height. |
duration | The new duration to store in the message object. 0 if you do not want to change it. |
dc_msg_t * dc_msg_new | ( | dc_context_t * | context, |
int | viewtype | ||
) |
Create new message object.
Message objects are needed eg. for sending messages using dc_send_msg(). Moreover, they are returned eg. 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.
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. |
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.
msg | The message object. |
width | Width in pixels, if known. 0 if you don't know or don't care. |
height | Height in pixels, if known. 0 if you don't know or don't care. |
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.
msg | The message object. |
duration | Length in milliseconds. 0 if you don't know or don't care. |
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.
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 | Mime type of the file. NULL if you don't know or don't care. |
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.
msg | The message object. |
text | Message text. |
void dc_msg_unref | ( | dc_msg_t * | msg | ) |
Free a message object.
Message objects are created eg. by dc_get_msg().
msg | The message object to free. If NULL is given, nothing is done. |