MessageOpen
From TrillWiki
The messageOpen function will open a message window to a particular person or channel on a certain medium. If the window is already open it will bring the window to the front of the screen.
Compatibility: 2.0 and higher
Contents |
Syntax
plugin_send(MYGUID, "messageOpen", 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
MessageOpen 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 for the window.
- connection_id
- The connection for the window.
- name
- The address of the person to send the message to.
- location
- If a multi-person chat window is being opened, fill in location to be the name of the chat session. Otherwise leave this as NULL.
- window_id
- Used only when opening up an existing window. If you are opening a new window, leave this as 0.
- extra_information_size
- The size of the extra_information structure.
- extra_information
- Additional message window information, described in a message_options_t structure as detailed below.
- display_name
- Fill in the display name of the window (if different than the name param).
Return Value
Negative value on error, window_id on success.
Remarks
A message will not be sent when included with a messageOpen.
This function is used for the owners of the medium only. It will not generate a medium_windowRequest and some mediums may not function properly without knowing that the window is created. The best way to open up a new window on a medium that is not owned by you is to do a messageSend with an empty message.
See also: messageSend
Additional Structures
message_options_t
struct message_options_t
{
unsigned int struct_size;
int global_mode;
int bold;
int italics;
int underline;
int style;
int size;
int background;
int foreground;
int num_colors;
int images;
int images_status;
int max_length;
int disabled;
char *disable_message;
int logging_off;
char *logging_name;
char *echo_name;
int echo_off;
int is_contact;
int initiated;
int irc_style;
struct nicklist_entry_t *nicklist;
/* 3.0
*/
int video;
int audio;
};
- global_mode
- The edit area will apply all formatting to the whole message (ie: if bold is on, everything will be bold, not just a certain portion of text).
- bold
- The medium supports bold text.
- italics
- The medium supports italic text.
- underline
- The medium supports underlined text.
- style
- In the future when font styles are supported, this will allow support to be turned on/off for it.
- background
- The medium supports background colors.
- foreground
- The medium supports foreground colors.
- num_colors
- The number of colors supported for foreground and background. Leave this as 0 if they support all colors.
- images
- If the images are allowed to be included within messages.
- images_status
- Images are allowed on the medium, just not currently.
- max_length
- The maximum size of a message allowed on the network. Trillian will not truncate currently, this is for future use.
- disabled
- If set the edit area of the message window will be disabled and no text can be entered.
- disable_message
- The text shown within a window when it is disabled.
- logging_off
- If set, logging for this window will be turned off. Useful if a medium has secure conversation mode and a setting stating they do not want secure conversations logged.
- logging_name
- The name to log conversations as. Leave this as NULL if you wish to use the default name (the address for the window).
- display_name
- The display name for the window.
- echo_name
- The name to echo text as within the window.
- echo_off
- Set this if the medium wishes to echo text itself or not have any echoing happen.
- is_contact
- Set this value if the window is already a contact. This will disable the add button and some other settings may be used.
- initiated
- If the window was initiated by the user, this should be set. If it was initiated by an incoming message, leave as 0. This will allow Trillian to know whether or not to play certain sounds and whether or not to steal focus.
- irc_style
- The text is echoed different for an IRC style window than for an IM style window.
- nicklist
- A list of people already within a chat room. This is not valid when location is NULL.
- video
- Video chat is supported.
- audio
- Audio chat is supported.
