Changeset eda54e4 for protocols/nogaim.h


Ignore:
Timestamp:
2007-10-12T00:08:58Z (17 years ago)
Author:
Wilmer van der Gaast <wilmer@…>
Branches:
master
Children:
a6df0b5
Parents:
82135c7 (diff), d444c09 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge from devel.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • protocols/nogaim.h

    r82135c7 reda54e4  
    9898        struct im_connection *ic;
    9999
     100        /* stuff used just for chat */
     101        /* The in_room variable is a list of handles (not nicks!), kind of
     102         * "nick list". This is how you can check who is in the group chat
     103         * already, for example to avoid adding somebody two times. */
    100104        GList *in_room;
    101105        GList *ignored;
    … …  
    103107        struct groupchat *next;
    104108        char *channel;
     109        /* The title variable contains the ID you gave when you created the
     110         * chat using imcb_chat_new(). */
    105111        char *title;
    106112        char joined;
     113        /* This is for you, you can add your own structure here to extend this
     114         * structure for your protocol's needs. */
    107115        void *data;
    108116};
    … …  
    123131struct prpl {
    124132        int options;
     133        /* You should set this to the name of your protocol.
     134         * - The user sees this name ie. when imcb_log() is used. */
    125135        const char *name;
    126136
    127137        /* Added this one to be able to add per-account settings, don't think
    128            it should be used for anything else. */
     138         * it should be used for anything else. You are supposed to use the
     139         * set_add() function to add new settings. */
    129140        void (* init)           (account_t *);
    130         /* These should all be pretty obvious. */
     141        /* The typical usage of the login() function:
     142         * - Create an im_connection using imcb_new() from the account_t parameter.
     143         * - Initialize your myproto_data struct - you should store all your protocol-specific data there.
     144         * - Save your custom structure to im_connection->proto_data.
     145         * - Use proxy_connect() to connect to the server.
     146         */
    131147        void (* login)          (account_t *);
     148        /* Implementing this function is optional. */
    132149        void (* keepalive)      (struct im_connection *);
     150        /* In this function you should:
     151         * - Tell the server about you are logging out.
     152         * - g_free() your myproto_data struct as BitlBee does not know how to
     153         *   properly do so.
     154         */
    133155        void (* logout)         (struct im_connection *);
    134156       
     157        /* This function is called when the user wants to send a message to a handle.
     158         * - 'to' is a handle, not a nick
     159         * - 'flags' may be ignored
     160         */
    135161        int  (* buddy_msg)      (struct im_connection *, char *to, char *message, int flags);
     162        /* This function is called then the user uses the /away IRC command.
     163         * - 'state' contains the away reason.
     164         * - 'message' may be ignored if your protocol does not support it.
     165         */
    136166        void (* set_away)       (struct im_connection *, char *state, char *message);
     167        /* Implementing this function is optional. */
    137168        void (* get_away)       (struct im_connection *, char *who);
     169        /* Implementing this function is optional. */
    138170        int  (* send_typing)    (struct im_connection *, char *who, int flags);
    139171       
    140         /* For now BitlBee doesn't really handle groups, just set it to NULL. */
     172        /* 'name' is a handle to add/remove. For now BitlBee doesn't really
     173         * handle groups, just set it to NULL, so you can ignore that
     174         * parameter. */
    141175        void (* add_buddy)      (struct im_connection *, char *name, char *group);
    142176        void (* remove_buddy)   (struct im_connection *, char *name, char *group);
    143177       
    144         /* Block list stuff. */
     178        /* Block list stuff. Implementing these are optional. */
    145179        void (* add_permit)     (struct im_connection *, char *who);
    146180        void (* add_deny)       (struct im_connection *, char *who);
    … …  
    151185       
    152186        /* Request profile info. Free-formatted stuff, the IM module gives back
    153            this info via imcb_log(). */
     187           this info via imcb_log(). Implementing these are optional. */
    154188        void (* get_info)       (struct im_connection *, char *who);
    155189        void (* set_my_name)    (struct im_connection *, char *name);
    … …  
    157191       
    158192        /* Group chat stuff. */
     193        /* This is called when the user uses the /invite IRC command.
     194         * - 'who' may be ignored
     195         * - 'message' is a handle to invite
     196         */
    159197        void (* chat_invite)    (struct groupchat *, char *who, char *message);
     198        /* This is called when the user uses the /part IRC command in a group
     199         * chat. You just should tell the user about it, nothing more. */
    160200        void (* chat_leave)     (struct groupchat *);
     201        /* This is called when the user sends a message to the groupchat.
     202         * 'flags' may be ignored. */
    161203        void (* chat_msg)       (struct groupchat *, char *message, int flags);
     204        /* This is called when the user uses the /join #nick IRC command.
     205         * - 'who' is the handle of the nick
     206         */
    162207        struct groupchat *
    163208             (* chat_with)      (struct im_connection *, char *who);
     209        /* This is used when the user uses the /join #channel IRC command.  If
     210         * your protocol does not support publicly named group chats, then do
     211         * not implement this. */
    164212        struct groupchat *
    165213             (* chat_join)      (struct im_connection *, char *room, char *nick, char *password);
    166214       
     215        /* You can tell what away states your protocol supports, so that
     216         * BitlBee will try to map the IRC away reasons to them, or use
     217         * GAIM_AWAY_CUSTOM when calling skype_set_away(). */
    167218        GList *(* away_states)(struct im_connection *ic);
    168219       
    169         /* Mainly for AOL, since they think "Bung hole" == "Bu ngho le". *sigh* */
     220        /* Mainly for AOL, since they think "Bung hole" == "Bu ngho le". *sigh*
     221         * - Most protocols will just want to set this to g_strcasecmp().*/
    170222        int (* handle_cmp) (const char *who1, const char *who2);
    171223};
    … …  
    175227G_MODULE_EXPORT GSList *get_connections();
    176228G_MODULE_EXPORT struct prpl *find_protocol( const char *name );
     229/* When registering a new protocol, you should allocate space for a new prpl
     230 * struct, initialize it (set the function pointers to point to your
     231 * functions), finally call this function. */
    177232G_MODULE_EXPORT void register_protocol( struct prpl * );
    178233
    179234/* Connection management. */
     235/* You will need this function in prpl->login() to get an im_connection from
     236 * the account_t parameter. */
    180237G_MODULE_EXPORT struct im_connection *imcb_new( account_t *acc );
    181238G_MODULE_EXPORT void imcb_free( struct im_connection *ic );
     239/* Once you're connected, you should call this function, so that the user will
     240 * see the success. */
    182241G_MODULE_EXPORT void imcb_connected( struct im_connection *ic );
     242/* This can be used to disconnect when something went wrong (ie. read error
     243 * from the server). You probably want to set the second parameter to TRUE. */
    183244G_MODULE_EXPORT void imc_logout( struct im_connection *ic, int allow_reconnect );
    184245
    185246/* Communicating with the user. */
     247/* A printf()-like function to tell the user anything you want. */
    186248G_MODULE_EXPORT void imcb_log( struct im_connection *ic, char *format, ... ) G_GNUC_PRINTF( 2, 3 );
     249/* To tell the user an error, ie. before logging out when an error occurs. */
    187250G_MODULE_EXPORT void imcb_error( struct im_connection *ic, char *format, ... ) G_GNUC_PRINTF( 2, 3 );
     251/* To ask a your about something.
     252 * - 'msg' is the question.
     253 * - 'data' can be your custom struct - it will be passed to the callbacks.
     254 * - 'doit' or 'dont' will be called depending of the answer of the user.
     255 */
    188256G_MODULE_EXPORT void imcb_ask( struct im_connection *ic, char *msg, void *data, void *doit, void *dont );
    189257G_MODULE_EXPORT void imcb_ask_add( struct im_connection *ic, char *handle, const char *realname );
    190258
    191259/* Buddy management */
     260/* This function should be called for each handle which are visible to the
     261 * user, usually after a login, or if the user added a buddy and the IM
     262 * server confirms that the add was successful. Don't forget to do this! */
    192263G_MODULE_EXPORT void imcb_add_buddy( struct im_connection *ic, char *handle, char *group );
    193264G_MODULE_EXPORT void imcb_remove_buddy( struct im_connection *ic, char *handle, char *group );
    … …  
    197268
    198269/* Buddy activity */
     270/* To manipulate the status of a handle.
     271 * - flags can be |='d with OPT_* constants. You will need at least:
     272 *   OPT_LOGGED_IN and OPT_AWAY.
     273 * - 'state' and 'message' can be NULL */
    199274G_MODULE_EXPORT void imcb_buddy_status( struct im_connection *ic, const char *handle, int flags, const char *state, const char *message );
    200275/* Not implemented yet! */ G_MODULE_EXPORT void imcb_buddy_times( struct im_connection *ic, const char *handle, time_t login, time_t idle );
     276/* Call when a handle says something. 'flags' and 'sent_at may be just 0. */
    201277G_MODULE_EXPORT void imcb_buddy_msg( struct im_connection *ic, char *handle, char *msg, u_int32_t flags, time_t sent_at );
    202278G_MODULE_EXPORT void imcb_buddy_typing( struct im_connection *ic, char *handle, u_int32_t flags );
    … …  
    205281/* Groupchats */
    206282G_MODULE_EXPORT void imcb_chat_invited( struct im_connection *ic, char *handle, char *who, char *msg, GList *data );
     283/* These two functions are to create a group chat.
     284 * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
     285 *   channel name on IRC.
     286 * - After you have a groupchat pointer, you should add the handles, finally
     287 *   the user her/himself. At that point the group chat will be visible to the
     288 *   user, too. */
    207289G_MODULE_EXPORT struct groupchat *imcb_chat_new( struct im_connection *ic, char *handle );
    208290G_MODULE_EXPORT void imcb_chat_add_buddy( struct groupchat *b, char *handle );
     291/* To remove a handle from a group chat. Reason can be NULL. */
    209292G_MODULE_EXPORT void imcb_chat_remove_buddy( struct groupchat *b, char *handle, char *reason );
     293/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
    210294G_MODULE_EXPORT void imcb_chat_msg( struct groupchat *c, char *who, char *msg, u_int32_t flags, time_t sent_at );
    211295G_MODULE_EXPORT void imcb_chat_free( struct groupchat *c );
Note: See TracChangeset for help on using the changeset viewer.