source: protocols/nogaim.h @ 778ea8a

Last change on this file since 778ea8a was 0e788f5, checked in by Wilmer van der Gaast <wilmer@…>, at 2013-02-21T19:15:59Z

I'm still bored on a long flight. Wrote a script to automatically update
my copyright mentions since some were getting pretty stale. Left files not
touched since before 2012 alone so that this change doesn't touch almost
EVERY source file.
  • Property mode set to 100644
File size: 14.1 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., 59 Temple Place,
35  Suite 330, Boston, MA  02111-1307  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
73/* ok. now the fun begins. first we create a connection structure */
74struct im_connection
75{
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};
99
100struct groupchat {
101        struct im_connection *ic;
102
103        /* stuff used just for chat */
104        /* The in_room variable is a list of handles (not nicks!), kind of
105         * "nick list". This is how you can check who is in the group chat
106         * already, for example to avoid adding somebody two times. */
107        GList *in_room;
108        //GList *ignored;
109       
110        //struct groupchat *next;
111        /* The title variable contains the ID you gave when you created the
112         * chat using imcb_chat_new(). */
113        char *title;
114        /* Use imcb_chat_topic() to change this variable otherwise the user
115         * won't notice the topic change. */
116        char *topic;
117        char joined;
118        /* This is for you, you can add your own structure here to extend this
119         * structure for your protocol's needs. */
120        void *data;
121        void *ui_data;
122};
123
124struct buddy {
125        char name[80];
126        char show[BUDDY_ALIAS_MAXLEN];
127        int present;
128        time_t signon;
129        time_t idle;
130        int uc;
131        guint caps; /* woohoo! */
132        void *proto_data; /* what a hack */
133        struct im_connection *ic; /* the connection it belongs to */
134};
135
136struct buddy_action {
137        char *name;
138        char *description;
139};
140
141struct prpl {
142        int options;
143        /* You should set this to the name of your protocol.
144         * - The user sees this name ie. when imcb_log() is used. */
145        const char *name;
146        void *data;
147        /* Maximum Message Size of this protocol.
148         * - Introduced for OTR, in order to fragment large protocol messages.
149         * - 0 means "unlimited". */
150        unsigned int mms;
151
152        /* Added this one to be able to add per-account settings, don't think
153         * it should be used for anything else. You are supposed to use the
154         * set_add() function to add new settings. */
155        void (* init)           (account_t *);
156        /* The typical usage of the login() function:
157         * - Create an im_connection using imcb_new() from the account_t parameter.
158         * - Initialize your myproto_data struct - you should store all your protocol-specific data there.
159         * - Save your custom structure to im_connection->proto_data.
160         * - Use proxy_connect() to connect to the server.
161         */
162        void (* login)          (account_t *);
163        /* Implementing this function is optional. */
164        void (* keepalive)      (struct im_connection *);
165        /* In this function you should:
166         * - Tell the server about you are logging out.
167         * - g_free() your myproto_data struct as BitlBee does not know how to
168         *   properly do so.
169         */
170        void (* logout)         (struct im_connection *);
171       
172        /* This function is called when the user wants to send a message to a handle.
173         * - 'to' is a handle, not a nick
174         * - 'flags' may be ignored
175         */
176        int  (* buddy_msg)      (struct im_connection *, char *to, char *message, int flags);
177        /* This function is called then the user uses the /away IRC command.
178         * - 'state' contains the away reason.
179         * - 'message' may be ignored if your protocol does not support it.
180         */
181        void (* set_away)       (struct im_connection *, char *state, char *message);
182        /* Implementing this function is optional. */
183        void (* get_away)       (struct im_connection *, char *who);
184        /* Implementing this function is optional. */
185        int  (* send_typing)    (struct im_connection *, char *who, int flags);
186       
187        /* 'name' is a handle to add/remove. For now BitlBee doesn't really
188         * handle groups, just set it to NULL, so you can ignore that
189         * parameter. */
190        void (* add_buddy)      (struct im_connection *, char *name, char *group);
191        void (* remove_buddy)   (struct im_connection *, char *name, char *group);
192       
193        /* Block list stuff. Implementing these are optional. */
194        void (* add_permit)     (struct im_connection *, char *who);
195        void (* add_deny)       (struct im_connection *, char *who);
196        void (* rem_permit)     (struct im_connection *, char *who);
197        void (* rem_deny)       (struct im_connection *, char *who);
198        /* Doesn't actually have UI hooks. Not used at all, can be removed. */
199        void (* set_permit_deny)(struct im_connection *);
200       
201        /* Request profile info. Free-formatted stuff, the IM module gives back
202           this info via imcb_log(). Implementing these are optional. */
203        void (* get_info)       (struct im_connection *, char *who);
204        /* set_my_name is *DEPRECATED*, not used by the UI anymore. Use the
205           display_name setting instead. */
206        void (* set_my_name)    (struct im_connection *, char *name);
207        void (* set_name)       (struct im_connection *, char *who, char *name);
208       
209        /* Group chat stuff. */
210        /* This is called when the user uses the /invite IRC command.
211         * - 'who' may be ignored
212         * - 'message' is a handle to invite
213         */
214        void (* chat_invite)    (struct groupchat *, char *who, char *message);
215        /* This is called when the user uses the /part IRC command in a group
216         * chat. You just should tell the user about it, nothing more. */
217        void (* chat_leave)     (struct groupchat *);
218        /* This is called when the user sends a message to the groupchat.
219         * 'flags' may be ignored. */
220        void (* chat_msg)       (struct groupchat *, char *message, int flags);
221        /* This is called when the user uses the /join #nick IRC command.
222         * - 'who' is the handle of the nick
223         */
224        struct groupchat *
225             (* chat_with)      (struct im_connection *, char *who);
226        /* This is used when the user uses the /join #channel IRC command.  If
227         * your protocol does not support publicly named group chats, then do
228         * not implement this. */
229        struct groupchat *
230             (* chat_join)      (struct im_connection *, const char *room,
231                                 const char *nick, const char *password, set_t **sets);
232        /* Change the topic, if supported. Note that BitlBee expects the IM
233           server to confirm the topic change with a regular topic change
234           event. If it doesn't do that, you have to fake it to make it
235           visible to the user. */
236        void (* chat_topic)     (struct groupchat *, char *topic);
237       
238        /* If your protocol module needs any special info for joining chatrooms
239           other than a roomname + nickname, add them here. */
240        void (* chat_add_settings)      (account_t *acc, set_t **head);
241        void (* chat_free_settings)     (account_t *acc, set_t **head);
242       
243        /* You can tell what away states your protocol supports, so that
244         * BitlBee will try to map the IRC away reasons to them. If your
245         * protocol doesn't have any, just return one generic "Away". */
246        GList *(* away_states)(struct im_connection *ic);
247       
248        /* Mainly for AOL, since they think "Bung hole" == "Bu ngho le". *sigh*
249         * - Most protocols will just want to set this to g_strcasecmp().*/
250        int (* handle_cmp) (const char *who1, const char *who2);
251
252        /* Implement these callbacks if you want to use imcb_ask_auth() */
253        void (* auth_allow)     (struct im_connection *, const char *who);
254        void (* auth_deny)      (struct im_connection *, const char *who);
255
256        /* Incoming transfer request */
257        void (* transfer_request) (struct im_connection *, file_transfer_t *ft, char *handle );
258       
259        void (* buddy_data_add) (struct bee_user *bu);
260        void (* buddy_data_free) (struct bee_user *bu);
261       
262        GList *(* buddy_action_list) (struct bee_user *bu);
263        void *(* buddy_action) (struct bee_user *bu, const char *action, char * const args[], void *data);
264       
265        /* Some placeholders so eventually older plugins may cooperate with newer BitlBees. */
266        void *resv1;
267        void *resv2;
268        void *resv3;
269        void *resv4;
270        void *resv5;
271};
272
273/* im_api core stuff. */
274void nogaim_init();
275G_MODULE_EXPORT GSList *get_connections();
276G_MODULE_EXPORT struct prpl *find_protocol( const char *name );
277/* When registering a new protocol, you should allocate space for a new prpl
278 * struct, initialize it (set the function pointers to point to your
279 * functions), finally call this function. */
280G_MODULE_EXPORT void register_protocol( struct prpl * );
281
282/* Connection management. */
283/* You will need this function in prpl->login() to get an im_connection from
284 * the account_t parameter. */
285G_MODULE_EXPORT struct im_connection *imcb_new( account_t *acc );
286G_MODULE_EXPORT void imc_free( struct im_connection *ic );
287/* Once you're connected, you should call this function, so that the user will
288 * see the success. */
289G_MODULE_EXPORT void imcb_connected( struct im_connection *ic );
290/* This can be used to disconnect when something went wrong (ie. read error
291 * from the server). You probably want to set the second parameter to TRUE. */
292G_MODULE_EXPORT void imc_logout( struct im_connection *ic, int allow_reconnect );
293
294/* Communicating with the user. */
295/* A printf()-like function to tell the user anything you want. */
296G_MODULE_EXPORT void imcb_log( struct im_connection *ic, char *format, ... ) G_GNUC_PRINTF( 2, 3 );
297/* To tell the user an error, ie. before logging out when an error occurs. */
298G_MODULE_EXPORT void imcb_error( struct im_connection *ic, char *format, ... ) G_GNUC_PRINTF( 2, 3 );
299
300/* To ask a your about something.
301 * - 'msg' is the question.
302 * - 'data' can be your custom struct - it will be passed to the callbacks.
303 * - 'doit' or 'dont' will be called depending of the answer of the user.
304 */
305G_MODULE_EXPORT void imcb_ask( struct im_connection *ic, char *msg, void *data, query_callback doit, query_callback dont );
306G_MODULE_EXPORT void imcb_ask_with_free( struct im_connection *ic, char *msg, void *data, query_callback doit, query_callback dont, query_callback myfree );
307
308/* Two common questions you may want to ask:
309 * - X added you to his contact list, allow?
310 * - X is not in your contact list, want to add?
311 */
312G_MODULE_EXPORT void imcb_ask_auth( struct im_connection *ic, const char *handle, const char *realname );
313G_MODULE_EXPORT void imcb_ask_add( struct im_connection *ic, const char *handle, const char *realname );
314
315/* Buddy management */
316/* This function should be called for each handle which are visible to the
317 * user, usually after a login, or if the user added a buddy and the IM
318 * server confirms that the add was successful. Don't forget to do this! */
319G_MODULE_EXPORT void imcb_add_buddy( struct im_connection *ic, const char *handle, const char *group );
320G_MODULE_EXPORT void imcb_remove_buddy( struct im_connection *ic, const char *handle, char *group );
321G_MODULE_EXPORT struct buddy *imcb_find_buddy( struct im_connection *ic, char *handle );
322G_MODULE_EXPORT void imcb_rename_buddy( struct im_connection *ic, const char *handle, const char *realname );
323G_MODULE_EXPORT void imcb_buddy_nick_hint( struct im_connection *ic, const char *handle, const char *nick );
324G_MODULE_EXPORT void imcb_buddy_action_response( bee_user_t *bu, const char *action, char * const args[], void *data );
325
326G_MODULE_EXPORT void imcb_buddy_typing( struct im_connection *ic, const char *handle, uint32_t flags );
327G_MODULE_EXPORT struct bee_user *imcb_buddy_by_handle( struct im_connection *ic, const char *handle );
328G_MODULE_EXPORT void imcb_clean_handle( struct im_connection *ic, char *handle );
329
330/* Actions, or whatever. */
331int imc_away_send_update( struct im_connection *ic );
332int imc_chat_msg( struct groupchat *c, char *msg, int flags );
333
334void imc_add_allow( struct im_connection *ic, char *handle );
335void imc_rem_allow( struct im_connection *ic, char *handle );
336void imc_add_block( struct im_connection *ic, char *handle );
337void imc_rem_block( struct im_connection *ic, char *handle );
338
339/* Misc. stuff */
340char *set_eval_timezone( set_t *set, char *value );
341gboolean auto_reconnect( gpointer data, gint fd, b_input_condition cond );
342void cancel_auto_reconnect( struct account *a );
343
344#endif
Note: See TracBrowser for help on using the repository browser.