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

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

#include <mrmsg.h>

Public Member Functions

mrmsg_tmrmsg_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_text (mrmsg_t *msg, const char *text)
 Set the text of a message object. More...
 
mrpoortext_tmrmsg_get_summary (mrmsg_t *msg, mrchat_t *chat)
 Get a summary for a message. More...
 
int mrmsg_show_padlock (mrmsg_t *msg)
 Check if a padlock should be shown beside the message. More...
 
char * mrmsg_get_summarytext (mrmsg_t *msg, int approx_characters)
 Get a message summary as a single line of text. More...
 
mrpoortext_tmrmsg_get_mediainfo (mrmsg_t *msg)
 Get real author and title. More...
 
void mrmsg_save_param_to_disk (mrmsg_t *msg)
 can be used to add some additional, persistent information to a messages record.
 

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
 Type of the message. More...
 
int m_state
 Message state. More...
 
char * m_text
 message text or NULL if unset
 
mrparam_tm_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

void mrmsg_empty ( mrmsg_t msg)

Empty a message object.

Parameters
msgThe message object to empty.
Returns
None.
mrpoortext_t * mrmsg_get_mediainfo ( mrmsg_t msg)

Get real author and title.

(as return.text1, this is not always the sender, NULL if unknown) and title (return.text2, NULL if unknown) of a message.

For voice messages, the author the sender and the trackname is the sending time For music messages, we read the information from the filename We do not read ID3 and such at this stage, the needed libraries may be buggy and the whole stuff is way to complicated. However, this is not a great disadvantage, as the sender usually sets the filename in a way we expect it - if not, we simply print the whole filename as we do it for documents. All fine in any case :-)

Parameters
msgthe message object
Returns
poortext object that must be unref'd using mrpoortext_unref() when no longer used.
mrpoortext_t * mrmsg_get_summary ( mrmsg_t msg,
mrchat_t chat 
)

Get a summary for a message.

The last parameter can be set to speed up things if the chat object is already available; if not, it is faster to pass NULL here. The result must be freed using mrpoortext_unref(). Typically used to display a search result.

Returns
The returned summary is similar to mrchatlist_get_summary(), however, without "draft", "no messages" and so on.
char * mrmsg_get_summarytext ( mrmsg_t msg,
int  approx_characters 
)

Get a message summary as a single line of text.

Typically used for notifications. The returned value must be free()'d.

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_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
msgMessage to set the text for.
textText 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.
int mrmsg_show_padlock ( 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.
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
msgThe message object to free.

Member Data Documentation

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.

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_id

Message ID.

Special message IDs:

Normal message IDs are larger than these special ones.

int mrmsg_t::m_is_msgrmsg

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

0 otherwise.

mrparam_t* mrmsg_t::m_param

Additional paramter for the message.

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

int mrmsg_t::m_starred

Starred-state of the message.

0=no, 1=yes.

int mrmsg_t::m_state

Message state.

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

time_t mrmsg_t::m_timestamp

Unix time the message was sended or received.

0 if unset.

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.

int mrmsg_t::m_type

Type of the message.

  • MR_MSG_TEXT (10)
  • MR_MSG_IMAGE (20) - m_param may contain MRP_FILE, MRP_WIDTH, MRP_HEIGHT
  • MR_MSG_GIF (21) - m_param may contain MRP_FILE, MRP_WIDTH, MRP_HEIGHT
  • MR_MSG_AUDIO (40) - m_param may contain MRP_FILE, MRP_DURATION
  • MR_MSG_VOICE (41) - m_param may contain MRP_FILE, MRP_DURATION
  • MR_MSG_VIDEO (50) - m_param may contain MRP_FILE, MRP_WIDTH, MRP_HEIGHT, MRP_DURATION
  • MR_MSG_FILE (60) - m_param may contain MRP_FILE

Undefined types are filed under MR_MSG_UNDEFINED (0).


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