source: protocols/nogaim.h @ 1c7b646

Last change on this file since 1c7b646 was 5a8afc3, checked in by dequis <dx@…>, at 2016-11-21T06:58:47Z

Manual merge with wilmer's approach to handling missing protocols

Turns out he already implemented pretty much the same thing in the
parson branch... last year.

The differences between the two approaches are subtle (there aren't too
many ways to do this, some lines are the exact same thing) but I decided
I like his version better, so this mostly reverts a handful of my
changes while keeping others. The main advantage of his approach is that
no fake protocols are registered, no actual prpl functions are called,
and the missing prpl is a singleton constant.

New things compared to the implementation in the other branch:

  • The explain_unknown_protocol() function.
  • Fixed named chatrooms throwing a warning and losing the "account" setting when saving. See changes in irc_im.c
  • Fixed the "server" setting dropping when saving. See account.c

Differences with my previous implementation:

  • Accounts with missing protocols don't autoconnect
  • 'account list' marks them as "(missing!)"
  • Property mode set to 100644
File size: 15.7 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
142/* This enum takes a few things from libpurple and a few things from old OPT_ flags.
143 * The only flag that was used before this struct was PRPL_OPT_NOOTR.
144 *
145 * The libpurple ones only use the same values as the PurpleProtocolOptions
146 * enum for convenience, but there's no promise of direct compatibility with
147 * those values. As of libpurple 2.8.0 they use up to 0x800 (1 << 11), which is
148 * a nice coincidence.
149 */
150typedef enum {
151        /* The protocol doesn't use passwords
152         * Mirrors libpurple's OPT_PROTO_NO_PASSWORD */
153        PRPL_OPT_NO_PASSWORD = 1 << 4,
154
155        /* The protocol doesn't require passwords, but may use them
156         * Mirrors libpurple's OPT_PROTO_PASSWORD_OPTIONAL */
157        PRPL_OPT_PASSWORD_OPTIONAL = 1 << 7,
158
159        /* The protocol is not suitable for OTR, see OPT_NOOTR */
160        PRPL_OPT_NOOTR = 1 << 12,
161} prpl_options_t;
162
163struct prpl {
164        int options;
165        /* You should set this to the name of your protocol.
166         * - The user sees this name ie. when imcb_log() is used. */
167        const char *name;
168        void *data;
169        /* Maximum Message Size of this protocol.
170         * - Introduced for OTR, in order to fragment large protocol messages.
171         * - 0 means "unlimited". */
172        unsigned int mms;
173
174        /* Added this one to be able to add per-account settings, don't think
175         * it should be used for anything else. You are supposed to use the
176         * set_add() function to add new settings. */
177        void (* init)           (account_t *);
178        /* The typical usage of the login() function:
179         * - Create an im_connection using imcb_new() from the account_t parameter.
180         * - Initialize your myproto_data struct - you should store all your protocol-specific data there.
181         * - Save your custom structure to im_connection->proto_data.
182         * - Use proxy_connect() to connect to the server.
183         */
184        void (* login)          (account_t *);
185        /* Implementing this function is optional. */
186        void (* keepalive)      (struct im_connection *);
187        /* In this function you should:
188         * - Tell the server about you are logging out.
189         * - g_free() your myproto_data struct as BitlBee does not know how to
190         *   properly do so.
191         */
192        void (* logout)         (struct im_connection *);
193
194        /* This function is called when the user wants to send a message to a handle.
195         * - 'to' is a handle, not a nick
196         * - 'flags' may be ignored
197         */
198        int (* buddy_msg)      (struct im_connection *, char *to, char *message, int flags);
199        /* This function is called then the user uses the /away IRC command.
200         * - 'state' contains the away reason.
201         * - 'message' may be ignored if your protocol does not support it.
202         */
203        void (* set_away)       (struct im_connection *, char *state, char *message);
204        /* Implementing this function is optional. */
205        int (* send_typing)    (struct im_connection *, char *who, int flags);
206
207        /* 'name' is a handle to add/remove. For now BitlBee doesn't really
208         * handle groups, just set it to NULL, so you can ignore that
209         * parameter. */
210        void (* add_buddy)      (struct im_connection *, char *name, char *group);
211        void (* remove_buddy)   (struct im_connection *, char *name, char *group);
212
213        /* Block list stuff. Implementing these are optional. */
214        void (* add_permit)     (struct im_connection *, char *who);
215        void (* add_deny)       (struct im_connection *, char *who);
216        void (* rem_permit)     (struct im_connection *, char *who);
217        void (* rem_deny)       (struct im_connection *, char *who);
218
219        /* Request profile info. Free-formatted stuff, the IM module gives back
220           this info via imcb_log(). Implementing these are optional. */
221        void (* get_info)       (struct im_connection *, char *who);
222
223        /* Group chat stuff. */
224        /* This is called when the user uses the /invite IRC command.
225         * - 'who' may be ignored
226         * - 'message' is a handle to invite
227         */
228        void (* chat_invite)    (struct groupchat *, char *who, char *message);
229        /* This is called when the user uses the /kick IRC command.
230         * - 'who' is a handle to kick
231         * - 'message' is a kick message or NULL
232         */
233        void (* chat_kick)      (struct groupchat *, char *who, const char *message);
234        /* This is called when the user uses the /part IRC command in a group
235         * chat. You just should tell the user about it, nothing more. */
236        void (* chat_leave)     (struct groupchat *);
237        /* This is called when the user sends a message to the groupchat.
238         * 'flags' may be ignored. */
239        void (* chat_msg)       (struct groupchat *, char *message, int flags);
240        /* This is called when the user uses the /join #nick IRC command.
241         * - 'who' is the handle of the nick
242         */
243        struct groupchat *
244        (* chat_with)      (struct im_connection *, char *who);
245        /* This is used when the user uses the /join #channel IRC command.  If
246         * your protocol does not support publicly named group chats, then do
247         * not implement this. */
248        struct groupchat *
249        (* chat_join)      (struct im_connection *, const char *room,
250                            const char *nick, const char *password, set_t **sets);
251        /* Change the topic, if supported. Note that BitlBee expects the IM
252           server to confirm the topic change with a regular topic change
253           event. If it doesn't do that, you have to fake it to make it
254           visible to the user. */
255        void (* chat_topic)     (struct groupchat *, char *topic);
256
257        /* If your protocol module needs any special info for joining chatrooms
258           other than a roomname + nickname, add them here. */
259        void (* chat_add_settings)      (account_t *acc, set_t **head);
260        void (* chat_free_settings)     (account_t *acc, set_t **head);
261
262        /* You can tell what away states your protocol supports, so that
263         * BitlBee will try to map the IRC away reasons to them. If your
264         * protocol doesn't have any, just return one generic "Away". */
265        GList *(* away_states)(struct im_connection *ic);
266
267        /* Mainly for AOL, since they think "Bung hole" == "Bu ngho le". *sigh*
268         * - Most protocols will just want to set this to g_strcasecmp().*/
269        int (* handle_cmp) (const char *who1, const char *who2);
270
271        /* Implement these callbacks if you want to use imcb_ask_auth() */
272        void (* auth_allow)     (struct im_connection *, const char *who);
273        void (* auth_deny)      (struct im_connection *, const char *who);
274
275        /* Incoming transfer request */
276        void (* transfer_request) (struct im_connection *, file_transfer_t *ft, char *handle);
277
278        void (* buddy_data_add) (struct bee_user *bu);
279        void (* buddy_data_free) (struct bee_user *bu);
280
281        GList *(* buddy_action_list) (struct bee_user *bu);
282        void *(* buddy_action) (struct bee_user *bu, const char *action, char * const args[], void *data);
283
284        /* If null, equivalent to handle_cmp( ic->acc->user, who ) */
285        gboolean (* handle_is_self) (struct im_connection *, const char *who);
286
287        /* This sets/updates the im_connection->chatlist field with a
288         * bee_chat_info_t GSList. This function should ensure the
289         * bee_chat_list_finish() function gets called at some point
290         * after the chat list is completely updated.
291         */
292        void (* chat_list) (struct im_connection *, const char *server);
293
294        /* Some placeholders so eventually older plugins may cooperate with newer BitlBees. */
295        void *resv1;
296        void *resv2;
297        void *resv3;
298        void *resv4;
299        void *resv5;
300};
301
302struct plugin_info
303{
304        guint abiver;
305        const char *name;
306        const char *version;
307        const char *description;
308        const char *author;
309        const char *url;
310};
311
312#ifdef WITH_PLUGINS
313G_MODULE_EXPORT GList *get_plugins();
314#endif
315
316/* im_api core stuff. */
317void nogaim_init();
318G_MODULE_EXPORT GList *get_protocols();
319G_MODULE_EXPORT GList *get_protocols_disabled();
320G_MODULE_EXPORT GSList *get_connections();
321G_MODULE_EXPORT struct prpl *find_protocol(const char *name);
322G_MODULE_EXPORT gboolean is_protocol_disabled(const char *name);
323G_MODULE_EXPORT char *explain_unknown_protocol(const char *name);
324/* When registering a new protocol, you should allocate space for a new prpl
325 * struct, initialize it (set the function pointers to point to your
326 * functions), finally call this function. */
327G_MODULE_EXPORT void register_protocol(struct prpl *);
328
329/* Connection management. */
330/* You will need this function in prpl->login() to get an im_connection from
331 * the account_t parameter. */
332G_MODULE_EXPORT struct im_connection *imcb_new(account_t *acc);
333G_MODULE_EXPORT void imc_free(struct im_connection *ic);
334/* Once you're connected, you should call this function, so that the user will
335 * see the success. */
336G_MODULE_EXPORT void imcb_connected(struct im_connection *ic);
337/* This can be used to disconnect when something went wrong (ie. read error
338 * from the server). You probably want to set the second parameter to TRUE. */
339G_MODULE_EXPORT void imc_logout(struct im_connection *ic, int allow_reconnect);
340
341/* Communicating with the user. */
342/* A printf()-like function to tell the user anything you want. */
343G_MODULE_EXPORT void imcb_log(struct im_connection *ic, char *format, ...) G_GNUC_PRINTF(2, 3);
344/* To tell the user an error, ie. before logging out when an error occurs. */
345G_MODULE_EXPORT void imcb_error(struct im_connection *ic, char *format, ...) G_GNUC_PRINTF(2, 3);
346
347/* To ask a your about something.
348 * - 'msg' is the question.
349 * - 'data' can be your custom struct - it will be passed to the callbacks.
350 * - 'doit' or 'dont' will be called depending of the answer of the user.
351 */
352G_MODULE_EXPORT void imcb_ask(struct im_connection *ic, char *msg, void *data, query_callback doit,
353                              query_callback dont);
354G_MODULE_EXPORT void imcb_ask_with_free(struct im_connection *ic, char *msg, void *data, query_callback doit,
355                                        query_callback dont, query_callback myfree);
356
357/* Two common questions you may want to ask:
358 * - X added you to his contact list, allow?
359 * - X is not in your contact list, want to add?
360 */
361G_MODULE_EXPORT void imcb_ask_auth(struct im_connection *ic, const char *handle, const char *realname);
362G_MODULE_EXPORT void imcb_ask_add(struct im_connection *ic, const char *handle, const char *realname);
363
364/* Buddy management */
365/* This function should be called for each handle which are visible to the
366 * user, usually after a login, or if the user added a buddy and the IM
367 * server confirms that the add was successful. Don't forget to do this! */
368G_MODULE_EXPORT void imcb_add_buddy(struct im_connection *ic, const char *handle, const char *group);
369G_MODULE_EXPORT void imcb_remove_buddy(struct im_connection *ic, const char *handle, char *group);
370G_MODULE_EXPORT void imcb_rename_buddy(struct im_connection *ic, const char *handle, const char *realname);
371G_MODULE_EXPORT void imcb_buddy_nick_hint(struct im_connection *ic, const char *handle, const char *nick);
372G_MODULE_EXPORT void imcb_buddy_nick_change(struct im_connection *ic, const char *handle, const char *nick);
373G_MODULE_EXPORT void imcb_buddy_action_response(bee_user_t *bu, const char *action, char * const args[], void *data);
374
375G_MODULE_EXPORT void imcb_buddy_typing(struct im_connection *ic, const char *handle, guint32 flags);
376G_MODULE_EXPORT struct bee_user *imcb_buddy_by_handle(struct im_connection *ic, const char *handle);
377
378G_GNUC_DEPRECATED G_MODULE_EXPORT void imcb_clean_handle(struct im_connection *ic, char *handle);
379
380/* Actions, or whatever. */
381int imc_away_send_update(struct im_connection *ic);
382int imc_chat_msg(struct groupchat *c, char *msg, int flags);
383
384void imc_add_allow(struct im_connection *ic, char *handle);
385void imc_rem_allow(struct im_connection *ic, char *handle);
386void imc_add_block(struct im_connection *ic, char *handle);
387void imc_rem_block(struct im_connection *ic, char *handle);
388
389/* Misc. stuff */
390char *set_eval_timezone(set_t *set, char *value);
391gboolean auto_reconnect(gpointer data, gint fd, b_input_condition cond);
392void cancel_auto_reconnect(struct account *a);
393
394#endif
Note: See TracBrowser for help on using the repository browser.