source: protocols/bee.h @ ff468a7

Last change on this file since ff468a7 was a33ee0f, checked in by jgeboski <jgeboski@…>, at 2016-09-20T03:39:05Z

Added an interface for the listing of existing chatrooms

Several protocols can provide a list of existing chatrooms that a user
is able join. This is crucial for the usage of several protocols, most
notably Purple and Facebook.

Plugins wishing to support this extended functionality must implement
the new prpl->chat_list() function. This implemented function will in
most cases send a remote request for the list of chatrooms. Once the
list of chatrooms is obtained, a bee_chat_info_t GSList must be created
and assigned to the im_connection->chatlist field. Then a call to the
bee_chat_list_finish() is needed to display the list to the user.

The chat list is maintained entirely by the plugin, so it is important
to ensure all pointers related to the chat list remain valid until the
chat list is set to NULL. This list is used internally by bitlbee to
calculate indexes, which then allows the user to join a chat with an
index, rather than some random identifier. It also important to ensure
the list is properly freed whenever it is updated, or when the account
is disconnect via the prpl->logout() function.

On the user interface side of things, the 'chat list' subcommand was
recommissioned. For a user to list the existing chat rooms:

chat list <account id>

Afterwards a user can join a chatroom in the list with its index. This
extends the functionality of the 'chat add' subcommand by adding in
support for the exclamation point operator to denote an index.

chat add <account id> !<index> [channel]

  • Property mode set to 100644
File size: 9.0 KB
Line 
1/********************************************************************\
2  * BitlBee -- An IRC to other IM-networks gateway                     *
3  *                                                                    *
4  * Copyright 2002-2010 Wilmer van der Gaast and others                *
5  \********************************************************************/
6
7/* Stuff to handle, save and search buddies                             */
8
9/*
10  This program is free software; you can redistribute it and/or modify
11  it under the terms of the GNU General Public License as published by
12  the Free Software Foundation; either version 2 of the License, or
13  (at your option) any later version.
14
15  This program is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  GNU General Public License for more details.
19
20  You should have received a copy of the GNU General Public License with
21  the Debian GNU/Linux distribution in /usr/share/common-licenses/GPL;
22  if not, write to the Free Software Foundation, Inc., 51 Franklin St.,
23  Fifth Floor, Boston, MA  02110-1301  USA
24*/
25
26#ifndef __BEE_H__
27#define __BEE_H__
28
29struct bee_ui_funcs;
30struct groupchat;
31
32typedef struct bee {
33        /* Settings. See set.h for how these work. The UI can add its
34           own settings here. */
35        struct set *set;
36
37        GSList *users;  /* struct bee_user */
38        GSList *groups; /* struct bee_group */
39        struct account *accounts; /* TODO(wilmer): Use GSList here too? */
40
41        /* Symbolic, to refer to the local user (who has no real bee_user
42           object). Not to be used by anything except so far imcb_chat_add/
43           remove_buddy(). */
44        struct bee_user *user;
45
46        /* Fill in the callbacks for events you care about. */
47        const struct bee_ui_funcs *ui;
48
49        /* And this one will be passed to every callback for any state the
50           UI may want to keep. */
51        void *ui_data;
52} bee_t;
53
54bee_t *bee_new();
55void bee_free(bee_t *b);
56
57/* TODO(wilmer): Kill at least the OPT_ flags that have an equivalent here. */
58typedef enum {
59        BEE_USER_ONLINE = 1,    /* Compatibility with old OPT_LOGGED_IN flag */
60        BEE_USER_AWAY = 4,      /* Compatibility with old OPT_AWAY flag */
61        BEE_USER_MOBILE = 8,    /* Compatibility with old OPT_MOBILE flag */
62        BEE_USER_LOCAL = 256,   /* Locally-added contacts (not in real contact list) */
63        BEE_USER_SPECIAL = 512, /* Denotes a user as being special */
64        BEE_USER_NOOTR = 4096,  /* Per-user version of OPT_NOOTR */
65} bee_user_flags_t;
66
67typedef struct bee_user {
68        struct im_connection *ic;
69        char *handle;
70        char *fullname;
71        char *nick;
72        struct bee_group *group;
73
74        bee_user_flags_t flags;
75        char *status;     /* NULL means available, anything else is an away state. */
76        char *status_msg; /* Status and/or away message. */
77
78        /* Set using imcb_buddy_times(). */
79        time_t login_time, idle_time;
80
81        bee_t *bee;
82        void *ui_data;
83        void *data; /* Can be used by the IM module. */
84} bee_user_t;
85
86typedef struct bee_chat_info {
87        char *title;
88        char *topic;
89} bee_chat_info_t;
90
91/* This one's mostly used so save space and make it easier (cheaper) to
92   compare groups of contacts, etc. */
93typedef struct bee_group {
94        char *key;  /* Lower case version of the name. */
95        char *name;
96} bee_group_t;
97
98typedef struct bee_ui_funcs {
99        void (*imc_connected)(struct im_connection *ic);
100        void (*imc_disconnected)(struct im_connection *ic);
101
102        gboolean (*user_new)(bee_t *bee, struct bee_user *bu);
103        gboolean (*user_free)(bee_t *bee, struct bee_user *bu);
104        /* Set the fullname first, then call this one to notify the UI. */
105        gboolean (*user_fullname)(bee_t *bee, bee_user_t *bu);
106        gboolean (*user_nick_hint)(bee_t *bee, bee_user_t *bu, const char *hint);
107        /* Notify the UI when an existing user is moved between groups. */
108        gboolean (*user_group)(bee_t *bee, bee_user_t *bu);
109        /* State info is already updated, old is provided in case the UI needs a diff. */
110        gboolean (*user_status)(bee_t *bee, struct bee_user *bu, struct bee_user *old);
111        /* On every incoming message. sent_at = 0 means unknown. */
112        gboolean (*user_msg)(bee_t *bee, bee_user_t *bu, const char *msg, guint32 flags, time_t sent_at);
113        /* Flags currently defined (OPT_TYPING/THINKING) in nogaim.h. */
114        gboolean (*user_typing)(bee_t *bee, bee_user_t *bu, guint32 flags);
115        /* CTCP-like stuff (buddy action) response */
116        gboolean (*user_action_response)(bee_t *bee, bee_user_t *bu, const char *action, char * const args[],
117                                         void *data);
118
119        /* Called at creation time. Don't show to the user until s/he is
120           added using chat_add_user().  UI state can be stored via c->data. */
121        gboolean (*chat_new)(bee_t *bee, struct groupchat *c);
122        gboolean (*chat_free)(bee_t *bee, struct groupchat *c);
123        /* System messages of any kind. */
124        gboolean (*chat_log)(bee_t *bee, struct groupchat *c, const char *text);
125        gboolean (*chat_msg)(bee_t *bee, struct groupchat *c, bee_user_t *bu, const char *msg, guint32 flags, time_t sent_at);
126        gboolean (*chat_add_user)(bee_t *bee, struct groupchat *c, bee_user_t *bu);
127        gboolean (*chat_remove_user)(bee_t *bee, struct groupchat *c, bee_user_t *bu, const char *reason);
128        gboolean (*chat_topic)(bee_t *bee, struct groupchat *c, const char *new_topic, bee_user_t *bu);
129        gboolean (*chat_name_hint)(bee_t *bee, struct groupchat *c, const char *name);
130        gboolean (*chat_invite)(bee_t *bee, bee_user_t *bu, const char *name, const char *msg);
131
132        struct file_transfer* (*ft_in_start)(bee_t * bee, bee_user_t * bu, const char *file_name, size_t file_size);
133        gboolean (*ft_out_start)(struct im_connection *ic, struct file_transfer *ft);
134        void (*ft_close)(struct im_connection *ic, struct file_transfer *ft);
135        void (*ft_finished)(struct im_connection *ic, struct file_transfer *ft);
136
137        void (*log)(bee_t *bee, const char *tag, const char *msg);
138        gboolean (*user_nick_change)(bee_t *bee, bee_user_t *bu, const char *hint);
139} bee_ui_funcs_t;
140
141
142/* bee.c */
143bee_t *bee_new();
144void bee_free(bee_t *b);
145
146/* bee_user.c */
147bee_user_t *bee_user_new(bee_t *bee, struct im_connection *ic, const char *handle, bee_user_flags_t flags);
148int bee_user_free(bee_t *bee, bee_user_t *bu);
149bee_user_t *bee_user_by_handle(bee_t *bee, struct im_connection *ic, const char *handle);
150int bee_user_msg(bee_t *bee, bee_user_t *bu, const char *msg, int flags);
151bee_group_t *bee_group_by_name(bee_t *bee, const char *name, gboolean creat);
152void bee_group_free(bee_t *bee);
153
154/* Callbacks from IM modules to core: */
155/* Buddy activity */
156/* To manipulate the status of a handle.
157 * - flags can be |='d with OPT_* constants. You will need at least:
158 *   OPT_LOGGED_IN and OPT_AWAY.
159 * - 'state' and 'message' can be NULL */
160G_MODULE_EXPORT void imcb_buddy_status(struct im_connection *ic, const char *handle, int flags, const char *state,
161                                       const char *message);
162G_MODULE_EXPORT void imcb_buddy_status_msg(struct im_connection *ic, const char *handle, const char *message);
163G_MODULE_EXPORT void imcb_buddy_times(struct im_connection *ic, const char *handle, time_t login, time_t idle);
164/* Call when a handle says something. 'flags' and 'sent_at may be just 0. */
165G_MODULE_EXPORT void imcb_buddy_msg(struct im_connection *ic, const char *handle, const char *msg, guint32 flags,
166                                    time_t sent_at);
167G_MODULE_EXPORT void imcb_notify_email(struct im_connection *ic, char *format, ...) G_GNUC_PRINTF(2, 3);
168
169/* bee_chat.c */
170/* These two functions are to create a group chat.
171 * - imcb_chat_new(): the 'handle' parameter identifies the chat, like the
172 *   channel name on IRC.
173 * - After you have a groupchat pointer, you should add the handles, finally
174 *   the user her/himself. At that point the group chat will be visible to the
175 *   user, too. */
176G_MODULE_EXPORT struct groupchat *imcb_chat_new(struct im_connection *ic, const char *handle);
177G_MODULE_EXPORT void imcb_chat_name_hint(struct groupchat *c, const char *name);
178G_MODULE_EXPORT void imcb_chat_free(struct groupchat *c);
179/* To tell BitlBee 'who' said 'msg' in 'c'. 'flags' and 'sent_at' can be 0. */
180G_MODULE_EXPORT void imcb_chat_msg(struct groupchat *c, const char *who, char *msg, guint32 flags, time_t sent_at);
181/* System messages specific to a groupchat, so they can be displayed in the right context. */
182G_MODULE_EXPORT void imcb_chat_log(struct groupchat *c, char *format, ...);
183/* To tell BitlBee 'who' changed the topic of 'c' to 'topic'. */
184G_MODULE_EXPORT void imcb_chat_topic(struct groupchat *c, char *who, char *topic, time_t set_at);
185G_MODULE_EXPORT void imcb_chat_add_buddy(struct groupchat *c, const char *handle);
186/* To remove a handle from a group chat. Reason can be NULL. */
187G_MODULE_EXPORT void imcb_chat_remove_buddy(struct groupchat *c, const char *handle, const char *reason);
188G_MODULE_EXPORT int bee_chat_msg(bee_t *bee, struct groupchat *c, const char *msg, int flags);
189G_MODULE_EXPORT struct groupchat *bee_chat_by_title(bee_t *bee, struct im_connection *ic, const char *title);
190G_MODULE_EXPORT void imcb_chat_invite(struct im_connection *ic, const char *name, const char *who, const char *msg);
191
192G_MODULE_EXPORT void bee_chat_list_finish(struct im_connection *ic);
193
194#endif /* __BEE_H__ */
Note: See TracBrowser for help on using the repository browser.