ContactlistEnumerate

From TrillWiki

Will deliver the contact list one by one to a callback function provided.

Compatibility: 1.0 and higher

Contents 1 Syntax 2 Parameters 3 Return Value 4 Remarks

Syntax

plugin_send(MYGUID, "contactlistEnumerate", struct contactlist_enum_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

ContactlistEnumerate utilitizes the contactlist_enum_t structure.

struct contactlist_enum_t
{
    unsigned int                struct_size;

    char                        *medium;

    int                         connection_id;

    ttkCallback                 callback;
    
    void                        *data;

    /* 2.0
     */
    char                        *section;
};

medium

String for the medium. This value can be "all" if you wish to enumerate through all contacts.

connection_id

The connection id of a specific medium. If medium is "all", this value is ignored.

callback

The callback to receive the enumeration notifications.

data

Data passed to the callback.

Return Value

Negative value on error, 0 on success.

Remarks

The callback function will be an enumeration notification function. Therefore it will receive enum_start, enum_add and enum_finish. For each enum_add, the data passed in will be a struct contactlist_entry_t. The fields will be filled out as follows:

medium

A string representing the medium the contact is on

name

The name of the contact as seen in the contact list.

real_name

The real name of the contact. The name field may be changed to a "display name". This field contains the actual name used on the network.

status

The status of the contact at that specific time. This status can vary depending on the network. Non-specific network statuses are "recent-online" and "recent-offline" which signify that the contact has just signed on. The other statuses are network specific.

connection_id

The connection ID this contact is on. Since a user may be on more than one connection, you may receive the contact multiple times with different connection IDs. A connection ID of -1 means that the contact is not on any specific connection at this time.