MessageReceive

From TrillWiki

The messageReceive function is used to let Trillian know when a message comes in on a certain medium. Trillian will then add the message to the appropriate window or request from the medium that a window be opened and then add.

Compatibility: 2.0 and higher

Contents 1 Syntax 2 Parameters 3 Return Value 4 Remarks

Syntax

plugin_send(MYGUID, "messageReceive", struct message_t *);

Note that all Trillian functions and notifications begin with a lower-case letter, despite the Wiki requirement that all pages start with a capital letter.

Parameters

MessageReceive utilitizes the message_t structure.

struct message_t
{
    unsigned int                struct_size;

    char                        *medium;
    int                         connection_id;

    char                        *name;
    char                        *type;
    char                        *text;

    char                        *location;

    void                        *extra_information;
    
    /* 2.0 
     */
    int                         window_id;
    unsigned int                extra_information_size;
    unsigned int                time_stamp;

    char                        *display_name;
    char                        *section;

    /* 3.0
     */
    struct capability_t         *capability_list;
    int                         text_len;
    int                         message_id;
};

medium

The medium to receive the message on.

connection_id

The connection to receive the message on.

name

The name the message was received from.

type

Type of message to received. Options for this include: incoming_privateMessage, incoming_groupMessage, information_standard, incoming_privateAction, incoming_groupAction, outgoing_groupMessage, outgoing_privateMessage, outgoing_privateAction, outgoing_groupAction. An action is something similar to a /me currently available. An information_standard is a message sent to the window that is a status-like message, such as if someone joins a chat or someone logs off, etc.

text

Text to send.

window_id

The window_id of the message window. This may be 0 if it is not known. If this is non-zero it will override the other variables given to locate the window.

time_stamp

The time the message was received. If this value is 0, the current time will be used.

Return Value

Originally under 2.0, messageReceive returned a negative value on error, 0 on success.

Under 3.0 and later, messageReceive returns a negative value on error or a message_id on success. This unique message_id is used to point to messages in the history, for message searching and also for things like messageIndividualUpdate.

Remarks

This can be used both for echoing (if echoing is turned off), as well as messages received from the network.

See also: messageSend