Changeset f6f5eee for protocols/bee.h


Ignore:
Timestamp:
2010-07-27T22:04:19Z (10 years ago)
Author:
Wilmer van der Gaast <wilmer@…>
Branches:
master
Children:
4255320
Parents:
82ca986
Message:

Source documentation update, including a short HACKING file.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • protocols/bee.h

    r82ca986 rf6f5eee  
    3232typedef struct bee
    3333{
     34        /* Settings. See set.h for how these work. The UI can add its
     35           own settings here. */
    3436        struct set *set;
    3537       
    36         GSList *users;
    37         GSList *groups;
     38        GSList *users;  /* struct bee_user */
     39        GSList *groups; /* struct bee_group */
    3840        struct account *accounts; /* TODO(wilmer): Use GSList here too? */
    3941       
    4042        /* Symbolic, to refer to the local user (who has no real bee_user
    4143           object). Not to be used by anything except so far imcb_chat_add/
    42            remove_buddy(). This seems slightly cleaner than abusing NULL. */
     44           remove_buddy(). */
    4345        struct bee_user *user;
    4446       
     47        /* Fill in the callbacks for events you care about. */
    4548        const struct bee_ui_funcs *ui;
     49       
     50        /* And this one will be passed to every callback for any state the
     51           UI may want to keep. */
    4652        void *ui_data;
    4753} bee_t;
     
    6672
    6773        bee_user_flags_t flags;
    68         char *status;
    69         char *status_msg;
     74        char *status;     /* NULL means available, anything else is an away state. */
     75        char *status_msg; /* Status and/or away message. */
    7076       
     77        /* Set using imcb_buddy_times(). */
    7178        time_t login_time, idle_time;
    7279       
     
    7582} bee_user_t;
    7683
     84/* This one's mostly used so save space and make it easier (cheaper) to
     85   compare groups of contacts, etc. */
    7786typedef struct bee_group
    7887{
    79         char *key;
     88        char *key;  /* Lower case version of the name. */
    8089        char *name;
    8190} bee_group_t;
     
    8897        gboolean (*user_new)( bee_t *bee, struct bee_user *bu );
    8998        gboolean (*user_free)( bee_t *bee, struct bee_user *bu );
     99        /* Set the fullname first, then call this one to notify the UI. */
    90100        gboolean (*user_fullname)( bee_t *bee, bee_user_t *bu );
    91101        gboolean (*user_nick_hint)( bee_t *bee, bee_user_t *bu, const char *hint );
     102        /* Notify the UI when an existing user is moved between groups. */
    92103        gboolean (*user_group)( bee_t *bee, bee_user_t *bu );
     104        /* State info is already updated, old is provided in case the UI needs a diff. */
    93105        gboolean (*user_status)( bee_t *bee, struct bee_user *bu, struct bee_user *old );
     106        /* On every incoming message. sent_at = 0 means unknown. */
    94107        gboolean (*user_msg)( bee_t *bee, bee_user_t *bu, const char *msg, time_t sent_at );
     108        /* Flags currently defined (OPT_TYPING/THINKING) in nogaim.h. */
    95109        gboolean (*user_typing)( bee_t *bee, bee_user_t *bu, guint32 flags );
    96110       
     111        /* Called at creation time. Don't show to the user until s/he is
     112           added using chat_add_user().  UI state can be stored via c->data. */
    97113        gboolean (*chat_new)( bee_t *bee, struct groupchat *c );
    98114        gboolean (*chat_free)( bee_t *bee, struct groupchat *c );
     115        /* System messages of any kind. */
    99116        gboolean (*chat_log)( bee_t *bee, struct groupchat *c, const char *text );
    100117        gboolean (*chat_msg)( bee_t *bee, struct groupchat *c, bee_user_t *bu, const char *msg, time_t sent_at );
     
    135152
    136153/* bee_chat.c */
    137 #if 0
    138 struct groupchat *imcb_chat_new( struct im_connection *ic, const char *handle );
    139 void imcb_chat_name_hint( struct groupchat *c, const char *name );
    140 void imcb_chat_free( struct groupchat *c );
    141 void imcb_chat_msg( struct groupchat *c, const char *who, char *msg, uint32_t flags, time_t sent_at );
    142 void imcb_chat_log( struct groupchat *c, char *format, ... );
    143 void imcb_chat_topic( struct groupchat *c, char *who, char *topic, time_t set_at );
    144 void imcb_chat_add_buddy( struct groupchat *b, const char *handle );
    145 void imcb_chat_remove_buddy( struct groupchat *b, const char *handle, const char *reason );
    146 static int remove_chat_buddy_silent( struct groupchat *b, const char *handle );
    147 #endif
    148 int bee_chat_msg( bee_t *bee, struct groupchat *c, const char *msg, int flags );
    149 struct groupchat *bee_chat_by_title( bee_t *bee, struct im_connection *ic, const char *title );
     154/* These two functions are to create a group chat.
     155 * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
     156 *   channel name on IRC.
     157 * - After you have a groupchat pointer, you should add the handles, finally 
     158 *   the user her/himself. At that point the group chat will be visible to the
     159 *   user, too. */
     160G_MODULE_EXPORT struct groupchat *imcb_chat_new( struct im_connection *ic, const char *handle );
     161G_MODULE_EXPORT void imcb_chat_name_hint( struct groupchat *c, const char *name );
     162G_MODULE_EXPORT void imcb_chat_free( struct groupchat *c );
     163/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
     164G_MODULE_EXPORT void imcb_chat_msg( struct groupchat *c, const char *who, char *msg, guint32 flags, time_t sent_at );
     165/* System messages specific to a groupchat, so they can be displayed in the right context. */
     166G_MODULE_EXPORT void imcb_chat_log( struct groupchat *c, char *format, ... );
     167/* To tell BitlBee 'who' changed the topic of 'c' to 'topic'. */
     168G_MODULE_EXPORT void imcb_chat_topic( struct groupchat *c, char *who, char *topic, time_t set_at );
     169G_MODULE_EXPORT void imcb_chat_add_buddy( struct groupchat *c, const char *handle );
     170/* To remove a handle from a group chat. Reason can be NULL. */
     171G_MODULE_EXPORT void imcb_chat_remove_buddy( struct groupchat *c, const char *handle, const char *reason );
     172G_MODULE_EXPORT int bee_chat_msg( bee_t *bee, struct groupchat *c, const char *msg, int flags );
     173G_MODULE_EXPORT struct groupchat *bee_chat_by_title( bee_t *bee, struct im_connection *ic, const char *title );
    150174
    151175#endif /* __BEE_H__ */
Note: See TracChangeset for help on using the changeset viewer.