source: protocols/nogaim.h @ 9698fc0

Last change on this file since 9698fc0 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: 14.9 KB
Line 
1/********************************************************************\
2  * BitlBee -- An IRC to other IM-networks gateway                     *
3  *                                                                    *
4  * Copyright 2002-2012 Wilmer van der Gaast and others                *
5  \********************************************************************/
6
7/*
8 * nogaim, soon to be known as im_api. Not a separate product (unless
9 * someone would be interested in such a thing), just a new name.
10 *
11 * Gaim without gaim - for BitlBee
12 *
13 * This file contains functions called by the Gaim IM-modules. It contains
14 * some struct and type definitions from Gaim.
15 *
16 * Copyright (C) 1998-1999, Mark Spencer <markster@marko.net>
17 *                          (and possibly other members of the Gaim team)
18 * Copyright 2002-2012 Wilmer van der Gaast <wilmer@gaast.net>
19 */
20
21/*
22  This program is free software; you can redistribute it and/or modify
23  it under the terms of the GNU General Public License as published by
24  the Free Software Foundation; either version 2 of the License, or
25  (at your option) any later version.
26
27  This program is distributed in the hope that it will be useful,
28  but WITHOUT ANY WARRANTY; without even the implied warranty of
29  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
30  GNU General Public License for more details.
31
32  You should have received a copy of the GNU General Public License with
33  the Debian GNU/Linux distribution in /usr/share/common-licenses/GPL;
34  if not, write to the Free Software Foundation, Inc., 51 Franklin St.,
35  Fifth Floor, Boston, MA  02110-1301  USA
36*/
37
38#ifndef _NOGAIM_H
39#define _NOGAIM_H
40
41#if (__sun)
42#include <inttypes.h>
43#else
44#include <stdint.h>
45#endif
46
47#include "bitlbee.h"
48#include "account.h"
49#include "proxy.h"
50#include "query.h"
51#include "md5.h"
52#include "ft.h"
53
54#define BUDDY_ALIAS_MAXLEN 388   /* because MSN names can be 387 characters */
55
56#define WEBSITE "http://www.bitlbee.org/"
57
58/* Sharing flags between all kinds of things. I just hope I won't hit any
59   limits before 32-bit machines become extinct. ;-) */
60#define OPT_LOGGED_IN   0x00000001
61#define OPT_LOGGING_OUT 0x00000002
62#define OPT_AWAY        0x00000004
63#define OPT_MOBILE      0x00000008
64#define OPT_DOES_HTML   0x00000010
65#define OPT_LOCALBUDDY  0x00000020 /* For nicks local to one groupchat */
66#define OPT_SLOW_LOGIN  0x00000040 /* I.e. Twitter Oauth @ login time */
67#define OPT_TYPING      0x00000100 /* Some pieces of code make assumptions */
68#define OPT_THINKING    0x00000200 /* about these values... Stupid me! */
69#define OPT_NOOTR       0x00001000 /* protocol not suitable for OTR */
70#define OPT_PONGS       0x00010000 /* Service sends us keep-alives */
71#define OPT_PONGED      0x00020000 /* Received a keep-alive during last interval */
72#define OPT_SELFMESSAGE 0x00080000 /* A message sent by self from another location */
73
74/* ok. now the fun begins. first we create a connection structure */
75struct im_connection {
76        account_t *acc;
77        uint32_t flags;
78
79        /* each connection then can have its own protocol-specific data */
80        void *proto_data;
81
82        /* all connections need an input watcher */
83        int inpa;
84        guint keepalive;
85
86        /* buddy list stuff. there is still a global groups for the buddy list, but
87         * we need to maintain our own set of buddies, and our own permit/deny lists */
88        GSList *permit;
89        GSList *deny;
90        int permdeny;
91
92        char *away;
93
94        /* BitlBee */
95        bee_t *bee;
96
97        GSList *groupchats;
98        GSList *chatlist;
99};
100
101struct groupchat {
102        struct im_connection *ic;
103
104        /* stuff used just for chat */
105        /* The in_room variable is a list of handles (not nicks!), kind of
106         * "nick list". This is how you can check who is in the group chat
107         * already, for example to avoid adding somebody two times. */
108        GList *in_room;
109        //GList *ignored;
110
111        //struct groupchat *next;
112        /* The title variable contains the ID you gave when you created the
113         * chat using imcb_chat_new(). */
114        char *title;
115        /* Use imcb_chat_topic() to change this variable otherwise the user
116         * won't notice the topic change. */
117        char *topic;
118        char joined;
119        /* This is for you, you can add your own structure here to extend this
120         * structure for your protocol's needs. */
121        void *data;
122        void *ui_data;
123};
124
125struct buddy {
126        char name[80];
127        char show[BUDDY_ALIAS_MAXLEN];
128        int present;
129        time_t signon;
130        time_t idle;
131        int uc;
132        guint caps; /* woohoo! */
133        void *proto_data; /* what a hack */
134        struct im_connection *ic; /* the connection it belongs to */
135};
136
137struct buddy_action {
138        char *name;
139        char *description;
140};
141
142struct prpl {
143        int options;
144        /* You should set this to the name of your protocol.
145         * - The user sees this name ie. when imcb_log() is used. */
146        const char *name;
147        void *data;
148        /* Maximum Message Size of this protocol.
149         * - Introduced for OTR, in order to fragment large protocol messages.
150         * - 0 means "unlimited". */
151        unsigned int mms;
152
153        /* Added this one to be able to add per-account settings, don't think
154         * it should be used for anything else. You are supposed to use the
155         * set_add() function to add new settings. */
156        void (* init)           (account_t *);
157        /* The typical usage of the login() function:
158         * - Create an im_connection using imcb_new() from the account_t parameter.
159         * - Initialize your myproto_data struct - you should store all your protocol-specific data there.
160         * - Save your custom structure to im_connection->proto_data.
161         * - Use proxy_connect() to connect to the server.
162         */
163        void (* login)          (account_t *);
164        /* Implementing this function is optional. */
165        void (* keepalive)      (struct im_connection *);
166        /* In this function you should:
167         * - Tell the server about you are logging out.
168         * - g_free() your myproto_data struct as BitlBee does not know how to
169         *   properly do so.
170         */
171        void (* logout)         (struct im_connection *);
172
173        /* This function is called when the user wants to send a message to a handle.
174         * - 'to' is a handle, not a nick
175         * - 'flags' may be ignored
176         */
177        int (* buddy_msg)      (struct im_connection *, char *to, char *message, int flags);
178        /* This function is called then the user uses the /away IRC command.
179         * - 'state' contains the away reason.
180         * - 'message' may be ignored if your protocol does not support it.
181         */
182        void (* set_away)       (struct im_connection *, char *state, char *message);
183        /* Implementing this function is optional. */
184        int (* send_typing)    (struct im_connection *, char *who, int flags);
185
186        /* 'name' is a handle to add/remove. For now BitlBee doesn't really
187         * handle groups, just set it to NULL, so you can ignore that
188         * parameter. */
189        void (* add_buddy)      (struct im_connection *, char *name, char *group);
190        void (* remove_buddy)   (struct im_connection *, char *name, char *group);
191
192        /* Block list stuff. Implementing these are optional. */
193        void (* add_permit)     (struct im_connection *, char *who);
194        void (* add_deny)       (struct im_connection *, char *who);
195        void (* rem_permit)     (struct im_connection *, char *who);
196        void (* rem_deny)       (struct im_connection *, char *who);
197
198        /* Request profile info. Free-formatted stuff, the IM module gives back
199           this info via imcb_log(). Implementing these are optional. */
200        void (* get_info)       (struct im_connection *, char *who);
201
202        /* Group chat stuff. */
203        /* This is called when the user uses the /invite IRC command.
204         * - 'who' may be ignored
205         * - 'message' is a handle to invite
206         */
207        void (* chat_invite)    (struct groupchat *, char *who, char *message);
208        /* This is called when the user uses the /kick IRC command.
209         * - 'who' is a handle to kick
210         * - 'message' is a kick message or NULL
211         */
212        void (* chat_kick)      (struct groupchat *, char *who, const char *message);
213        /* This is called when the user uses the /part IRC command in a group
214         * chat. You just should tell the user about it, nothing more. */
215        void (* chat_leave)     (struct groupchat *);
216        /* This is called when the user sends a message to the groupchat.
217         * 'flags' may be ignored. */
218        void (* chat_msg)       (struct groupchat *, char *message, int flags);
219        /* This is called when the user uses the /join #nick IRC command.
220         * - 'who' is the handle of the nick
221         */
222        struct groupchat *
223        (* chat_with)      (struct im_connection *, char *who);
224        /* This is used when the user uses the /join #channel IRC command.  If
225         * your protocol does not support publicly named group chats, then do
226         * not implement this. */
227        struct groupchat *
228        (* chat_join)      (struct im_connection *, const char *room,
229                            const char *nick, const char *password, set_t **sets);
230        /* Change the topic, if supported. Note that BitlBee expects the IM
231           server to confirm the topic change with a regular topic change
232           event. If it doesn't do that, you have to fake it to make it
233           visible to the user. */
234        void (* chat_topic)     (struct groupchat *, char *topic);
235
236        /* If your protocol module needs any special info for joining chatrooms
237           other than a roomname + nickname, add them here. */
238        void (* chat_add_settings)      (account_t *acc, set_t **head);
239        void (* chat_free_settings)     (account_t *acc, set_t **head);
240
241        /* You can tell what away states your protocol supports, so that
242         * BitlBee will try to map the IRC away reasons to them. If your
243         * protocol doesn't have any, just return one generic "Away". */
244        GList *(* away_states)(struct im_connection *ic);
245
246        /* Mainly for AOL, since they think "Bung hole" == "Bu ngho le". *sigh*
247         * - Most protocols will just want to set this to g_strcasecmp().*/
248        int (* handle_cmp) (const char *who1, const char *who2);
249
250        /* Implement these callbacks if you want to use imcb_ask_auth() */
251        void (* auth_allow)     (struct im_connection *, const char *who);
252        void (* auth_deny)      (struct im_connection *, const char *who);
253
254        /* Incoming transfer request */
255        void (* transfer_request) (struct im_connection *, file_transfer_t *ft, char *handle);
256
257        void (* buddy_data_add) (struct bee_user *bu);
258        void (* buddy_data_free) (struct bee_user *bu);
259
260        GList *(* buddy_action_list) (struct bee_user *bu);
261        void *(* buddy_action) (struct bee_user *bu, const char *action, char * const args[], void *data);
262
263        /* If null, equivalent to handle_cmp( ic->acc->user, who ) */
264        gboolean (* handle_is_self) (struct im_connection *, const char *who);
265
266        /* This sets/updates the im_connection->chatlist field with a
267         * bee_chat_info_t GSList. This function should ensure the
268         * bee_chat_list_finish() function gets called at some point
269         * after the chat list is completely updated.
270         */
271        void (* chat_list) (struct im_connection *, const char *server);
272
273        /* Some placeholders so eventually older plugins may cooperate with newer BitlBees. */
274        void *resv1;
275        void *resv2;
276        void *resv3;
277        void *resv4;
278        void *resv5;
279};
280
281struct plugin_info
282{
283        guint abiver;
284        const char *name;
285        const char *version;
286        const char *description;
287        const char *author;
288        const char *url;
289};
290
291#ifdef WITH_PLUGINS
292G_MODULE_EXPORT GList *get_plugins();
293#endif
294
295/* im_api core stuff. */
296void nogaim_init();
297G_MODULE_EXPORT GList *get_protocols();
298G_MODULE_EXPORT GList *get_protocols_disabled();
299G_MODULE_EXPORT GSList *get_connections();
300G_MODULE_EXPORT struct prpl *find_protocol(const char *name);
301G_MODULE_EXPORT gboolean is_protocol_disabled(const char *name);
302/* When registering a new protocol, you should allocate space for a new prpl
303 * struct, initialize it (set the function pointers to point to your
304 * functions), finally call this function. */
305G_MODULE_EXPORT void register_protocol(struct prpl *);
306
307/* Connection management. */
308/* You will need this function in prpl->login() to get an im_connection from
309 * the account_t parameter. */
310G_MODULE_EXPORT struct im_connection *imcb_new(account_t *acc);
311G_MODULE_EXPORT void imc_free(struct im_connection *ic);
312/* Once you're connected, you should call this function, so that the user will
313 * see the success. */
314G_MODULE_EXPORT void imcb_connected(struct im_connection *ic);
315/* This can be used to disconnect when something went wrong (ie. read error
316 * from the server). You probably want to set the second parameter to TRUE. */
317G_MODULE_EXPORT void imc_logout(struct im_connection *ic, int allow_reconnect);
318
319/* Communicating with the user. */
320/* A printf()-like function to tell the user anything you want. */
321G_MODULE_EXPORT void imcb_log(struct im_connection *ic, char *format, ...) G_GNUC_PRINTF(2, 3);
322/* To tell the user an error, ie. before logging out when an error occurs. */
323G_MODULE_EXPORT void imcb_error(struct im_connection *ic, char *format, ...) G_GNUC_PRINTF(2, 3);
324
325/* To ask a your about something.
326 * - 'msg' is the question.
327 * - 'data' can be your custom struct - it will be passed to the callbacks.
328 * - 'doit' or 'dont' will be called depending of the answer of the user.
329 */
330G_MODULE_EXPORT void imcb_ask(struct im_connection *ic, char *msg, void *data, query_callback doit,
331                              query_callback dont);
332G_MODULE_EXPORT void imcb_ask_with_free(struct im_connection *ic, char *msg, void *data, query_callback doit,
333                                        query_callback dont, query_callback myfree);
334
335/* Two common questions you may want to ask:
336 * - X added you to his contact list, allow?
337 * - X is not in your contact list, want to add?
338 */
339G_MODULE_EXPORT void imcb_ask_auth(struct im_connection *ic, const char *handle, const char *realname);
340G_MODULE_EXPORT void imcb_ask_add(struct im_connection *ic, const char *handle, const char *realname);
341
342/* Buddy management */
343/* This function should be called for each handle which are visible to the
344 * user, usually after a login, or if the user added a buddy and the IM
345 * server confirms that the add was successful. Don't forget to do this! */
346G_MODULE_EXPORT void imcb_add_buddy(struct im_connection *ic, const char *handle, const char *group);
347G_MODULE_EXPORT void imcb_remove_buddy(struct im_connection *ic, const char *handle, char *group);
348G_MODULE_EXPORT void imcb_rename_buddy(struct im_connection *ic, const char *handle, const char *realname);
349G_MODULE_EXPORT void imcb_buddy_nick_hint(struct im_connection *ic, const char *handle, const char *nick);
350G_MODULE_EXPORT void imcb_buddy_nick_change(struct im_connection *ic, const char *handle, const char *nick);
351G_MODULE_EXPORT void imcb_buddy_action_response(bee_user_t *bu, const char *action, char * const args[], void *data);
352
353G_MODULE_EXPORT void imcb_buddy_typing(struct im_connection *ic, const char *handle, guint32 flags);
354G_MODULE_EXPORT struct bee_user *imcb_buddy_by_handle(struct im_connection *ic, const char *handle);
355
356G_GNUC_DEPRECATED G_MODULE_EXPORT void imcb_clean_handle(struct im_connection *ic, char *handle);
357
358/* Actions, or whatever. */
359int imc_away_send_update(struct im_connection *ic);
360int imc_chat_msg(struct groupchat *c, char *msg, int flags);
361
362void imc_add_allow(struct im_connection *ic, char *handle);
363void imc_rem_allow(struct im_connection *ic, char *handle);
364void imc_add_block(struct im_connection *ic, char *handle);
365void imc_rem_block(struct im_connection *ic, char *handle);
366
367/* Misc. stuff */
368char *set_eval_timezone(set_t *set, char *value);
369gboolean auto_reconnect(gpointer data, gint fd, b_input_condition cond);
370void cancel_auto_reconnect(struct account *a);
371
372#endif
Note: See TracBrowser for help on using the repository browser.