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

#include <mrmsg.h>

Public Member Functions
mrmsg_t *	mrmsg_new ()
	Create new message object. More...

void	mrmsg_unref (mrmsg_t *msg)
	Free an mrmsg_t object created eg. More...

void	mrmsg_empty (mrmsg_t *msg)
	Empty a message object. More...

void	mrmsg_set_type (mrmsg_t *msg, int type)
	Set the type of a message. More...

void	mrmsg_set_text (mrmsg_t msg, const char text)
	Set the text of a message object. More...

void	mrmsg_set_file (mrmsg_t msg, const char file)
	Set the file belonging to a message. 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...

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

mrpoortext_t *	mrmsg_get_mediainfo (mrmsg_t *msg)
	Get real author and title. More...

int	mrmsg_get_showpadlock (mrmsg_t *msg)
	Check if a padlock should be shown beside the message. More...

mrpoortext_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_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_increation (mrmsg_t *msg)
	Check if a message is still in creation. More...

void	mrmsg_save_param_to_disk (mrmsg_t *msg)
	Add additional, persistent information to a message record. More...

Public Attributes
uint32_t	m_id
	Message ID. More...

uint32_t	m_from_id
	Contact ID of the sender. More...

uint32_t	m_to_id
	Contact ID of the recipient. More...

uint32_t	m_chat_id
	Chat ID the message belongs to. More...

time_t	m_timestamp
	Unix time the message was sended or received. More...

int	m_type
	Message type. More...

int	m_state
	Message state. More...

char *	m_text
	Message text. More...

mrparam_t *	m_param
	Additional paramter for the message. More...

int	m_starred
	Starred-state of the message. More...

int	m_is_msgrmsg
	Set to 1 if the message was sent by another messenger. 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

mrmsg_t * mrmsg_new ( )

Create new message object.

Message objects are needed eg. for sending messages using mrmailbox_send_msg(). Moreover, they are returned eg. from mrmailbox_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.

Returns: The created message object.

void mrmsg_unref ( mrmsg_t * msg )

Free an mrmsg_t object created eg.

by mrmsg_new() or mrmailbox_get_msg(). This also free()s all strings; so if you set up the object yourself, make sure to use strdup()!

Parameters

msg	The message object to free.

Returns: None.

void mrmsg_empty ( mrmsg_t * msg )

Empty a message object.

Parameters

msg	The message object to empty.

Returns: None.

void mrmsg_set_type	(	mrmsg_t *	msg,
		int	type
	)

Set the type of a message.

See mrmailbox_send_msg() for some examples.

Parameters

msg	The message object to modify.
type	Type to set for the message. Possible types are MR_MSG_TEXT (10), MR_MSG_IMAGE (20), MR_MSG_GIF (21), MR_MSG_AUDIO (40), MR_MSG_VOICE (41), MR_MSG_VIDEO (50) or MR_MSG_FILE (60).

Returns: None.

void mrmsg_set_text	(	mrmsg_t *	msg,
		const char *	text
	)

Set the text of a message object.

The text is not modified in the database, this function is only a helper to set up a message object to be sent afterwards. The type of the message object is not changed implicitly to MR_MSG_TEXT when using this function. Previously set texts are free()'d.

Parameters

msg	Message to set the text for.
text	Text to set. The function creates a copy of the given text so that it can be free()'d just after this function is called.

Returns: None.

void mrmsg_set_file	(	mrmsg_t *	msg,
		const char *	file
	)

Set the file belonging to a message.

The file may be an image, a video, an audio file, an PDF and so on. This function is a shortcut for mrparam_set(msg->m_param, MRP_FILE, file)

Parameters

msg	The message object to modify.
file	Path, filename and extension to set for the given message.

Returns: None.

int mrmsg_get_type ( mrmsg_t * msg )

Get the type of the message.

Parameters

msg	The 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.

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

msg	The message object.

Returns: The state 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

msg	The 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

msg	The 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

msg	The 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

msg	The message object.

Returns: String containing the mime type. Must be free()'d after usage. NULL is never returned.

mrpoortext_t * mrmsg_get_mediainfo ( mrmsg_t * msg )

Get real author and title.

For voice messages, the author is the sender and the trackname is the sending time.
For music messages and videos, we read the information from the filename (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

msg	The message object.

Returns: mrpoortext_t object that contains the author as mrpoortext_t::m_text1 and the title as mrpoortext_t::m_text2. Both may be NULL if unknown. The returned object must be freed using mrpoortext_unref() when no longer used.

int mrmsg_get_showpadlock ( mrmsg_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.

mrpoortext_t * mrmsg_get_summary	(	mrmsg_t *	msg,
		mrchat_t *	chat
	)

Get a summary for a message.

Typically used to display a search result.

Parameters

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.

Returns: The returned summary is similar to mrchatlist_get_summary(), however, without "draft", "no messages" and so on. The result must be freed using mrpoortext_unref().

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

msg	The message object.
approx_characters	Rough length of the expected string.

Returns: A summary for the given messages. The returned string must be free()'d.

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

msg	The 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

msg	The message object.

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

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

msg	the message object

Returns: 1=message is still in creation (<filename>.increation exists), 0=message no longer in creation

void mrmsg_save_param_to_disk ( mrmsg_t * msg )

Add additional, persistent information to a message record.

Normally, this function is not needed; message records are created by mrmailbox_send_msg() or mrmailbox_send_text_msg() and modified by actions of the user. However, for rare cases, it might be necessary to save an paramter later to disk. For this purpose, use this function.

Parameters

msg	The message object.

Returns: None.

Member Data Documentation

uint32_t mrmsg_t::m_id

Message ID.

Special message IDs:

MR_MSG_ID_MARKER1 (1) - any user-defined marker, see mrmailbox_get_chat_msgs()
MR_MSG_ID_DAYMARKER (9) - in a list, the next message is on a new day, useful to show headlines, see mrmailbox_get_chat_msgs()

Normal message IDs are larger than these special ones.

uint32_t mrmsg_t::m_from_id

Contact ID of the sender.

0 if unset. See mrcontact_t::m_id for special IDs. Use mrmailbox_get_contact() to load details about this contact.

uint32_t mrmsg_t::m_to_id

Contact ID of the recipient.

0 if unset. See mrcontact_t::m_id for special IDs. Use mrmailbox_get_contact() to load details about this contact.

uint32_t mrmsg_t::m_chat_id

Chat ID the message belongs to.

0 if unset. See mrchat_t::m_id for special IDs. Use mrmailbox_get_chat() to load details about the chat.

time_t mrmsg_t::m_timestamp

Unix time the message was sended or received.

0 if unset.

int mrmsg_t::m_type

Message type.

It is recommended to use mrmsg_set_type() and mrmsg_get_type() to access this field.

int mrmsg_t::m_state

Message state.

It is recommended to use mrmsg_get_state() to access this field.

char* mrmsg_t::m_text

Message text.

NULL if unset. It is recommended to use mrmsg_set_text() and mrmsg_get_text() to access this field.

mrparam_t* mrmsg_t::m_param

Additional paramter for the message.

MRP_FILE, MRP_WIDTH, MRP_HEIGHT etc. depends on the type. Never a NULL-pointer.

int mrmsg_t::m_starred

Starred-state of the message.

0=no, 1=yes.

int mrmsg_t::m_is_msgrmsg

Set to 1 if the message was sent by another messenger.

0 otherwise.

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

/home/bpetersen/projects/deltachat-core/src/mrmsg.h
/home/bpetersen/projects/deltachat-core/src/mrmsg.c

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation