Changeset acd61b9 for protocols/nogaim.h


Ignore:
Timestamp:
2007-10-08T00:04:33Z (17 years ago)
Author:
Miklos Vajna <vmiklos@…>
Branches:
master
Children:
2896674
Parents:
9334cc2
Message:

Improve comments in nogaim.h so that writing support for new protocols will be
easier.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • protocols/nogaim.h

    r9334cc2 racd61b9  
    9898
    9999        /* stuff used just for chat */
     100        /* The in_room variable is a list of handles (not nicks!), kind of
     101         * "nick list". This is how you can check who is in the group chat
     102         * already, for example to avoid adding somebody two times. */
    100103        GList *in_room;
    101104        GList *ignored;
    … …  
    104107        struct groupchat *next;
    105108        char *channel;
     109        /* The title variable contains the ID you gave when you created the
     110         * chat using imcb_chat_new(). */
    106111        char *title;
    107112        char joined;
     113        /* This is for you, you can add your own structure here to extend this
     114         * structure for your protocol's needs. */
    108115        void *data;
    109116};
    … …  
    124131struct prpl {
    125132        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. */
    126135        const char *name;
    127136
    128137        /* Added this one to be able to add per-account settings, don't think
    129            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. */
    130140        void (* init)           (account_t *);
    131         /* 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         */
    132147        void (* login)          (account_t *);
     148        /* Implementing this function is optional. */
    133149        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         */
    134155        void (* logout)         (struct im_connection *);
    135156       
     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         */
    136161        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         */
    137166        void (* set_away)       (struct im_connection *, char *state, char *message);
     167        /* Implementing this function is optional. */
    138168        void (* get_away)       (struct im_connection *, char *who);
     169        /* Implementing this function is optional. */
    139170        int  (* send_typing)    (struct im_connection *, char *who, int flags);
    140171       
    141         /* 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. */
    142175        void (* add_buddy)      (struct im_connection *, char *name, char *group);
    143176        void (* remove_buddy)   (struct im_connection *, char *name, char *group);
    144177       
    145         /* Block list stuff. */
     178        /* Block list stuff. Implementing these are optional. */
    146179        void (* add_permit)     (struct im_connection *, char *who);
    147180        void (* add_deny)       (struct im_connection *, char *who);
    … …  
    152185       
    153186        /* Request profile info. Free-formatted stuff, the IM module gives back
    154            this info via imcb_log(). */
     187           this info via imcb_log(). Implementing these are optional. */
    155188        void (* get_info)       (struct im_connection *, char *who);
    156189        void (* set_my_name)    (struct im_connection *, char *name);
    … …  
    158191       
    159192        /* 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         */
    160197        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. */
    161200        void (* chat_leave)     (struct groupchat *);
     201        /* This is called when the user sends a message to the groupchat.
     202         * 'flags' may be ignored. */
    162203        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         */
    163207        struct groupchat *
    164208             (* 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. */
    165212        struct groupchat *
    166213             (* chat_join)      (struct im_connection *, char *room, char *nick, char *password);
    167214       
     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(). */
    168218        GList *(* away_states)(struct im_connection *ic);
    169219       
    170         /* 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().*/
    171222        int (* handle_cmp) (const char *who1, const char *who2);
    172223};
    … …  
    176227G_MODULE_EXPORT GSList *get_connections();
    177228G_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. */
    178232G_MODULE_EXPORT void register_protocol( struct prpl * );
    179233
    180234/* Connection management. */
     235/* You will need this function in prpl->login() to get an im_connection from
     236 * the account_t parameter. */
    181237G_MODULE_EXPORT struct im_connection *imcb_new( account_t *acc );
    182238G_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. */
    183241G_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. */
    184244G_MODULE_EXPORT void imc_logout( struct im_connection *ic, int allow_reconnect );
    185245
    186246/* Communicating with the user. */
     247/* A printf()-like function to tell the user anything you want. */
    187248G_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. */
    188250G_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 */
    189256G_MODULE_EXPORT void imcb_ask( struct im_connection *ic, char *msg, void *data, void *doit, void *dont );
    190257G_MODULE_EXPORT void imcb_ask_add( struct im_connection *ic, char *handle, const char *realname );
    191258
    192259/* Buddy management */
     260/* This function should be called for each handle which are visible to the
     261 * user, usually after a login. */
    193262G_MODULE_EXPORT void imcb_add_buddy( struct im_connection *ic, char *handle, char *group );
    194263G_MODULE_EXPORT void imcb_remove_buddy( struct im_connection *ic, char *handle, char *group );
    … …  
    197266
    198267/* Buddy activity */
     268/* To manipulate the status of a handle.
     269 * - flags can be |='d with OPT_* constants. You will need at least:
     270 *   OPT_LOGGED_IN and OPT_AWAY.
     271 * - 'state' and 'message' can be NULL */
    199272G_MODULE_EXPORT void imcb_buddy_status( struct im_connection *ic, const char *handle, int flags, const char *state, const char *message );
    200273/* Not implemented yet! */ G_MODULE_EXPORT void imcb_buddy_times( struct im_connection *ic, const char *handle, time_t login, time_t idle );
     274/* Call when a handle says something. 'flags' and 'sent_at may be just 0. */
    201275G_MODULE_EXPORT void imcb_buddy_msg( struct im_connection *ic, char *handle, char *msg, u_int32_t flags, time_t sent_at );
    202276G_MODULE_EXPORT void imcb_buddy_typing( struct im_connection *ic, char *handle, u_int32_t flags );
    … …  
    204278/* Groupchats */
    205279G_MODULE_EXPORT void imcb_chat_invited( struct im_connection *ic, char *handle, char *who, char *msg, GList *data );
     280/* These two functions are to create a group chat.
     281 * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
     282 *   channel name on IRC.
     283 * - After you have a groupchat pointer, you should add the handles, finally
     284 *   the user her/himself. At that point the group chat will be visible to the
     285 *   user, too. */
    206286G_MODULE_EXPORT struct groupchat *imcb_chat_new( struct im_connection *ic, char *handle );
    207287G_MODULE_EXPORT void imcb_chat_add_buddy( struct groupchat *b, char *handle );
     288/* To remove a handle from a group chat. Reason can be NULL. */
    208289G_MODULE_EXPORT void imcb_chat_remove_buddy( struct groupchat *b, char *handle, char *reason );
     290/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
    209291G_MODULE_EXPORT void imcb_chat_msg( struct groupchat *c, char *who, char *msg, u_int32_t flags, time_t sent_at );
    210292G_MODULE_EXPORT void imcb_chat_removed( struct groupchat *c );
Note: See TracChangeset for help on using the changeset viewer.