ContactlistAdd

From TrillWiki

The contactlistAdd function adds a contact to the particular contact list specified by the struct, however will ask the user for the location in which to add them to.

Compatibility: 2.0 and higher

Contents 1 Syntax 2 Parameters 3 Return Value 4 Remarks

Syntax

plugin_send(MYGUID, "contactlistAdd", 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

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

name

The display name for the contact.

real_name

The address associated with the contact. (The value that never changes).

section

The Contact List to add the contact to. A NULL will specify the default section (My Contacts).

uri

A URI to associate with the contact when saving it to disk. This will be given to you on a medium_contactAdd notification on file load.

tooltip

The default tooltip for the contact when not using the enhanced tooltips.

group

The group to add the contact to.

menu_entry

The initial menu for the contact.

callback

The callback to use for this contact.

data

The user data to send with each notification sent to the callback.

Return Value

Negative value on error, 0 on success.

Remarks

The medium, group and uri or real_name are the main items that *need* to be within this call. The others can be set in response to a medium_contactAdd if you want to consolidate code. A contactlistUpdate can be called to set the remaining fields when that notification is sent.

If you do not know which group to add to yet (ie: you want to add a contact in response to the toolbar button being clicked from a message window), you may use contactlistAddGroupRequest to query the user for the group prior to adding.

Be sure to NULL out the menu and callback when the plugin stops (using contactlistUpdate).