ContactlistUpdate
From TrillWiki
The contactlistUpdate function updates some of the values for a contact.
Compatibility: 2.0 and higher
Contents |
Syntax
plugin_send(MYGUID, "contactlistUpdate", struct contactlist_entry_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
ContactlistUpdate utilitizes the contactlist_entry_t structure.
struct contactlist_entry_t
{
unsigned int struct_size;
char *medium;
int connection_id;
char *name;
char *real_name;
char *status;
/* 2.0 enhancement
*/
char *section;
char *uri;
char *tooltip;
int status_score;
int status_idle;
int status_block;
struct group_entry_t *group;
struct menu_entry_t *menu_entry;
ttkCallback callback;
void *data;
/* 3.0
*/
int status_warned;
int status_time;
int status_idle_time;
char *status_message;
};
- medium
- Medium for the the contact.
- connection_id
- Connection id for this status update. You must change the status for all connection id's that belong to this contact.
- name
- Display name for the contact.
- real_name
- The address associated with the contact. (The value that never changes).
- status
- Status to change this connection id to. The status must move from offline to online in order to get proper sign on alerts, etc. (Ie: do not directly go from offline -> away).
- status_message
- When the contact's status is not online or offline this is the text which is displayed underneath the name in icon view.
- section
- The Contact List of the contact to update. A NULL will specify the default section (My Contacts).
- uri
- The URI identifier for the contact (used when saving to disk and given on a medium_contactAdd notification.
- tooltip
- Default tooltip for the contact when the enhanced tooltip is not used.
- status_score
- The score for this particular status. Each status has a score for metacontacts to use to determine which contact to use for the default double click action. The scores used should be: 0 - offline, 2 - offline with offline messaging, 3 - away (such as DND or Not available), 5 - away (such as a custom away, or 'away', 10 - online
- status_idle
- If the medium supports an idle state which is not a separate status, this may be set to 1.
- status_block
- If the contact is blocked this is set to 1, else 0.
- menu_entry
- Menu to use for the contact. Anytime this changes, a destroy will be sent to the previous menu. If you do not wish to change the menu (ie are only updating the status), you should send the same pointer as you did initially so that a destroy is not sent. For details on menu_entry_t, see below.
- callback
- Callback to use for contactlist events.
- data
- Data sent with the above callback.
Return Value
Negative value on error, 0 on success.
Remarks
Please note that when you are updating a contact, some NULL values may be resetting a previous value set. IE: Dont initialize and only send a new status, you will have to fill it up with the old menu, display name, etc.
See also: contactlistRemove
Additional Structures
menu_entry_t
struct menu_entry_t {
unsigned int struct_size;
int menu_id;
int sub_menu_id;
int type;
int timeout;
int disabled;
int num_copies;
char *icon;
char *text;
char *shortcut;
void *data;
HWND hwnd;
struct menu_entry_t *sub_menu;
struct menu_entry_t *next_menu;
ttkCallback callback;
};
- menu_id
- The menu ID which is returned to you.
- sub_menu_id
- Must be -1.
- type
- Specifies the type of menu it will be. There are four types that are currently supported: MENU_TEXT, MENU_POPUP, MENU_SEPARATOR or MENU_CALLBACK. A MENU_TEXT type is just a normal menu entry. A MENU_POPUP is one that provides sub menus. A MENU_SEPARATOR is a horizontal separator that can separate a menu into sections to make it easier on the eyes to read. Lastly, the MENU_CALLBACK is a place holder that can be replaced when a menu is shown, this is good for dynamic menu areas that may change often and the plugin can be able to show the most current state of the menu at the time it is drawn.
- timeout
- Can either be a number for the number of times it is shown before it is hidden, or can be infinite (right now infinite is the only one that works).
- disabled
- If you want it unclickable or not.
- num_copies
- Must be 0.
- icon
- A name of the icon to use from the skin for the menu.
- text
- The text to write within the menu.
- shortcut
- If there is a shortcut key, add it here, such as 'ctrl-t'.
- data
- Data returned through the callback.
- sub_menu
- If there are sub_menu's to this entry, add the top of the chain here.
- next_menu
- If there are menu's below this entry, add the next one down here.
- callback
- The callback where menu notifications are sent.
