Mercurial > pidgin
annotate HACKING @ 1273:2153b0734e74
[gaim-migrate @ 1283]
import yahoo list (mostly so that it's used by bud_list_cache_exists and doesn't get used by other protocols)
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Thu, 14 Dec 2000 13:46:10 +0000 |
parents | 72692c70317e |
children | ab5dd2c7e7f8 |
rev | line source |
---|---|
639 | 1 A lot of people have tried to hack gaim, but haven't been able to because |
2 the code is just so horrid. Well, the code isn't getting better anytime | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
3 soon (I hate GNU indent), so to help all you would-be hackers help out |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
4 gaim, here's a brief tutorial on how gaim works. I'll quickly describe |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
5 the logical flow of things, then what you'll find in each of the source |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
6 files. As an added bonus, I'll try and describe as best I can how multiple |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
7 connections and multiple protocols work. Depending on how much I want |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
8 to avoid my final tomorrow I may even describe other parts of gaim that |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
9 I particularly want to brag about. Hopefully that's enough to get most |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
10 of you going. |
639 | 11 |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
12 If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
13 against the absolute latest CVS. I get really annoyed when I get patches |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
14 against the last released version, especially since I don't usually |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
15 have a copy of it on my computer, and gaim tends to change a lot between |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
16 versions. (I sometimes get annoyed when they're against CVS from 3 days |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
17 ago, but can't complain because it's usually my fault that I haven't |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
18 looked at the patch yet.) To get gaim from CVS (if you haven't already), |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
19 run the following commands: |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
20 |
774
b61607d6c2af
[gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
749
diff
changeset
|
21 $ export CVSROOT=:pserver:anonymous@cvs.gaim.sourceforge.net:/cvsroot/gaim |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
22 $ cvs login (hit enter as the password) |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
23 $ cvs co gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
24 (you'll see it getting all of the files) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
25 $ cd gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
26 $ ./gen |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
27 |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
28 You'll now have your normal gaim tree with ./configure and all. (If you |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
29 want to make your life really simple, learn how CVS works. CVS is your |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
30 friend.) To make a patch, just edit the files right there in that tree |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
31 (don't bother with two trees, or even two copies of the same file). Then |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
32 when you're ready to make your patch, simply run 'cvs diff -u >my.patch' |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
33 and send it off. |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
34 |
639 | 35 There's one little thing that's just a pet peeve, and it's really stupid. |
706
a9758452f3c4
[gaim-migrate @ 716]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
684
diff
changeset
|
36 In ./configure there's an --enable-debug option. This does two things: |
639 | 37 compiles with -Wall, and prints debugging information to stdout. The |
38 debugging information is printed to the debug window (which can be turned | |
39 on in the preferences) whether or not --enable-debug was selected. Most | |
40 of the information that's printed is useless anyway though; so the | |
41 --enable-debug option really doesn't do a whole lot. | |
42 | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
43 This file was last modified by $Author: warmenhoven $ on |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
44 $Date: 2000-12-12 07:56:53 -0500 (Tue, 12 Dec 2000) $. |
684
b29c92be568b
[gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
639
diff
changeset
|
45 |
639 | 46 |
47 PROGRAM FLOW | |
48 ============ | |
49 | |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
50 Before gaim does anything you can see, it initializes itself, which is |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
51 mostly just reading .gaimrc (handled by the functions in gaimrc.c) and |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
52 parsing command-line options. It then draws the login window by calling |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
53 show_login, and waits for input. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
54 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
55 At the login window, when "Accounts" is clicked, account_editor() is |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
56 called. This then displays all of the users and various information |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
57 about them. If the user clicks the "Signon" button instead, serv_login |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
58 is called. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
59 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
60 When the "Sign on/off" button is clicked, serv_login is passed the |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
61 username and the password for the account. If the password length is |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
62 zero (the password field is a character array rather than pointer so it |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
63 will not be NULL) then the Signon callback will prompt for the password |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
64 before calling serv_login. serv_login then signs in the user using the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
65 appropriate protocol. We'll assume TOC for the rest of this discussion; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
66 even the libfaim guys get scared by oscar.c, and I'll talk about the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
67 PRPLs later. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
68 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
69 After you're signed in (I'll skip that discussion - I doubt many people |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
70 are going to change the login process, since it pretty much just follows |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
71 PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
72 waits for input from two places: the server and the user. The first |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
73 place it gets input from after signon is usually the server, when the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
74 server tells Gaim which buddies are signed on. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
75 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
76 When there is information ready to be read from the server, toc_callback |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
77 is called (by GDK) to parse the incoming information. On an UPDATE, |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
78 serv_got_update is called, which takes care of things like notifying |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
79 conversation windows of the update if need be; notifying the plugins; |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
80 and finally, calling set_buddy. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
81 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
82 set_buddy is responsible for a lot of stuff, but most of it is done |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
83 implicitly. It's responsible for the sounds (which is just a call to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
84 play_sound), but the biggest thing it does is call new_group_show and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
85 new_buddy_show if necessary. There's only one group_show per group name, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
86 even between connections, and only one buddy_show per group_show per |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
87 buddy name, even between connections. (If that's not confusing enough, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
88 wait until I really start describing how the buddy list works.) |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
89 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
90 New connections happen the exact same way as described above. Each |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
91 aim_user can have one gaim_connection associated with it. aim_user and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
92 gaim_connection both have a protocol field; gaim_connection's should |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
93 be constant once it is set. (I'll talk about the gaim_connection struct |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
94 more later.) |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
95 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
96 When the user opens a new conversation window, new_conversation is called. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
97 That's easy enough. If there isn't a conversation with the person already |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
98 open (checked by calling find_conversation), show_conv is called to |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
99 create the new window. All sorts of neat things happen there, but it's |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
100 mostly drawing the window. show_conv is the best place to edit the UI. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
101 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
102 That's pretty much it for the quick tutorial. I know it wasn't much but |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
103 it's enough to get you started. Make sure you know GTK before you get too |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
104 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK. |
639 | 105 |
106 | |
107 SOURCE FILES | |
108 ============ | |
109 | |
110 about.c: | |
111 Not much to say here, just a few basic functions. | |
112 | |
113 aim.c: | |
114 This is where the main() function is. It takes care of a lot of the | |
115 initialization stuff, and showing the login window. It's pretty tiny | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
116 and there's not really much to edit in it. This has some of the most |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
117 pointless functions, like gaim_setup, which optionally turns off sounds |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
118 on signon. A lot of this file should actually be part of other files. |
639 | 119 |
120 away.c: | |
121 This takes care of most of the away stuff: setting the away message | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
122 (do_away_message); coming back (do_im_back); drawing the away window; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
123 etc. |
639 | 124 |
125 browser.c: | |
126 Code for opening a browser window. Most of the code is trying to deal | |
127 with Netscape. The most important function here is open_url. Have fun. | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
128 (This file may give you problems with GTK 2.0, because it uses parts |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
129 of GDK that it's not supposed to know about.) |
639 | 130 |
131 buddy.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
132 This takes care of not only nearly everything buddy-related (the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
133 buddy lists, the window, etc.), but also a lot of the code flow and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
134 util functions. Look for good things like find_buddy, set_buddy, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
135 and signoff here. |
639 | 136 |
137 buddy_chat.c: | |
138 This takes care of the buddy chat stuff. This used to be a lot bigger | |
139 until the chat and IM windows got merged in the code. Now it mostly | |
140 just takes care of chat-specific stuff, like ignoring people and | |
141 keeping track of who's in the room. This is also where the chat window | |
142 is created. | |
143 | |
144 conversation.c: | |
145 This is where most of the functions dealing with the IM and chat windows | |
146 are hidden. It tries to abstract things as much as possible, but doesn't | |
147 do a very good job. This is also where things like "Enter sends" and | |
148 "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
149 chat and IM toolbar (with the B/I/U/S buttons) are both built from |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
150 the same function, build_conv_toolbar. |
639 | 151 |
152 dialogs.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
153 A massive file with a lot of little utility functions. This is where all |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
154 of those little dialog windows are created. Things like the warn dialog |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
155 and the add buddy dialog are here. Not all of the dialogs in gaim are in |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
156 this file, though. But most of them are. This is also where do_import |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
157 is housed, to import buddy lists. (The actual buddy list parsing code |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
158 is in util.c for winaim lists and toc.c for gaim's own lists.) |
639 | 159 |
160 gaimrc.c: | |
161 This controls everything about the .gaimrc file. There's not really much | |
162 to say about it; this is probably one of the better designed and easier | |
163 to follow files in gaim. The important functions are towards the bottom. | |
164 | |
165 gnome_applet_mgr.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
166 This controls most things that are related to the applet. I don't like |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
167 looking at this file because it still has functionsLikeThis. But at |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
168 least it doesn't have many of them anymore. Anyway, this file isn't |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
169 very big because there's really not much difference between the panel |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
170 version and the app version. |
639 | 171 |
172 gtkhtml.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
173 This is really just one big hack. I recommend not looking at this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
174 file if you want to save your sanity. (It's going to be replaced |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
175 eventually anyway.) People have asked why we don't replace this with |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
176 GNOME's GtkHTML, or embed mozilla (yes, they were serious). There |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
177 are two reasons. The first is that doing that would cause gaim to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
178 require 6 extra libraries that nobody needs or wants or has. The |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
179 second is that we really don't need, or even want, a full-fledged |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
180 HTML viewer. We don't even want a normal HTML viewer because the text |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
181 that gets sent gets parsed and displayed different than normal HTML. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
182 (Try inserting a newline and you'll see what I mean.) We should only |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
183 support about 12 tags, not the 50 that normal HTML supports. |
639 | 184 |
185 gtkticker.c: | |
186 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that | |
187 widget. It's cool, and it's tiny. | |
188 | |
189 html.c: | |
190 Don't ask my why this is called html.c. Most of it is just grab_url, | |
191 which does like the name says; it downloads a URL to show in the | |
192 GtkHTML widget. http.c would be a more appropriate name, but that's OK. | |
193 | |
194 idle.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
195 This file used to be entirely #if 0'd out of existance. However, thanks |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
196 to some very generous people who submitted patches, this takes care of |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
197 reporting idle time (imagine that). It's a pretty straight-forward file. |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
198 This also takes care of the auto-away stuff. |
639 | 199 |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
200 multi.c: |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
201 This is the file that tries to take care of most of the major issues |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
202 with multiple connections. The best function in here by far is the |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
203 account_editor(). auto_login() is also in here (I'm just reading multi.h |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
204 now...). account_editor is really the only function that the UI needs |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
205 to be concerned with. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
206 |
639 | 207 oscar.c: |
208 One big hack of copied code. This is supposed to be the libfaim tie-in | |
209 in gaim. Most of it is just copied straight from faimtest, the small | |
210 program that comes with libfaim. I'm not even sure how half of it works, | |
211 if that makes you feel any better. | |
212 | |
213 perl.c: | |
214 This was basically copied straight from X-Chat through the power of | |
215 the GPL. Perl is the biggest, most confusing piece of C code I've ever | |
216 seen in my life (and keep in mind I'm a gaim hacker). I have a basic | |
217 idea of what's going on in it, but I couldn't tell you exactly. The | |
218 top half sets up perl and tells it what's going on and the bottom half | |
219 implements the AIM module. | |
220 | |
221 plugins.c: | |
222 This is the "plugin plug", as the file states. This file is probably | |
223 the only file in all of gaim that at the top has all of the functions | |
224 and global and static variables named out for you. It makes reading | |
225 it a little easier, but not by much. A lot of the code in here deals | |
226 with the plugin window rather than the plugins themselves. | |
227 | |
228 prefs.c: | |
229 The important function in here is build_prefs, but the most useful | |
230 function is gaim_button. build_prefs draws the window, and calls | |
231 gaim_button probably 30 or 40 times. (I don't really wanna run grep | |
232 | wc to count.) This is where you add the toggle button for gaim | |
233 preferences. It's very simple, and if you look at a couple of the | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
234 calls to gaim_button you'll figure it out right away. The new prefs |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
235 window uses a CList instead of a Notebook, and there's a pretty bad |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
236 hack to get it to work. I won't tell you what though. |
639 | 237 |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
238 prpl.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
239 This file is what lets gaim dynamically load protocols, sort of. All |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
240 of the actual dlopen(), dlsym() stuff is in plugins.c. But this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
241 contains all of the functions that the protocol plugin needs to call, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
242 and manages all of the protocols. It's a pretty simple file actually. |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
243 |
639 | 244 proxy.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
245 Adam (of libfaim glory) got bored one day and rewrote this file, so |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
246 now everything actually works. The main function is proxy_connect, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
247 which figures out which proxy you want to use (if you want to use one |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
248 at all) and passes off the data to the appropriate function. This file |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
249 should be pretty straight-forward. |
639 | 250 |
251 rvous.c: | |
252 This was originally going to be the stuff for all of the Buddy Icon | |
253 and Voice Chat stuff, but I got really sick of protocol hacking really | |
254 quick. Now it only houses the file transfer stuff, which only works | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
255 for TOC. ("Works" being a very subjective statement. This file needs |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
256 to be rewritten.) |
639 | 257 |
258 server.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
259 This is where all of the differentiation between the different protocols |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
260 is done. Nearly everything that's network related goes through here |
639 | 261 at one point or another. This has good things like serv_send_im and |
262 serv_got_update. Most of it should be pretty self-explanatory. | |
263 | |
264 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
265 The main function in this file is play_sound, which plays one of 8 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
266 (maybe 9?) sounds based on preferences. All that the rest of the code |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
267 should have to do is call play_sound(BUDDY_ARRIVE), for example, and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
268 this file will take care of determining if a sound should be played |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
269 and which file should be played. |
639 | 270 |
271 ticker.c: | |
272 Syd is just so cool. I really can't get over it. He let me come | |
273 visit him at Netscape one day, and I got to see all of their toys | |
274 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
275 ticker. This is also a damn cool file because it's got all of the | |
276 functions that you'd want right up at the top. Someday I want to be | |
277 as cool as Syd. | |
278 | |
279 toc.c: | |
280 This handles everything TOC-related, including parsing gaim's buddy | |
281 list. Most of this file is toc_callback, which parses the incoming | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
282 information from the server. I really don't like TOC though. (I've spent |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
283 waaayyyy too much time with TOC. I rewrote the signon process for this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
284 file at one point, so that read was only called when data was pending. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
285 Since then the TOC server has been blocking my IP (probably my own |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
286 stupid fault, sending bad strings or some such).) |
639 | 287 |
288 util.c: | |
289 There's not really a lot of cohesion to this file; it's just a lot of | |
290 stuff that happened to be thrown into it for no apparent reason. None | |
291 of it is particularly tasty; it's all just utility functions. Just | |
292 like the name says. | |
293 | |
294 | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
295 HOW THE BUDDY LIST WORKS |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
296 ======================== |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
297 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
298 The buddy list is a pain in the ass. Let me start off by saying that. The |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
299 most difficult part about getting gaim to do multiple connections was |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
300 the buddy list. In its current state it's very much like the UI for |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
301 0.10.x and earlier, which is what I was aiming for. However, the code |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
302 is completely different. And not much better. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
303 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
304 All of the buddy list stuff is in buddy.c, so you'll only have to have |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
305 that one file open (and possibly gaim.h for the struct definitions). There |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
306 are two sets of functions: those that deal with the buddy lists, and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
307 those that deal with the window. (I say lists because each connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
308 has their own buddy list, independent of the others, even though the UI |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
309 merges them.) |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
310 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
311 The buddy list functions work pretty much the same way they did before; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
312 except now that each buddy and group belongs to a connection, things |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
313 like find_buddy take an additional argument, the connection you want to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
314 search for the buddy in. Read gaim.h for a good list of them: find_buddy, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
315 find_group, add_buddy, remove_buddy, remove_group. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
316 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
317 The window is a lot more fun. There's really only one function that |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
318 does anything interesting, and that's set_buddy. (There's also things |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
319 like build_edit_tree, but that's boring.) set_buddy is called by |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
320 serv_got_update (and should only be called by that function) any time |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
321 a user signs on, signs off, goes away, comes back, goes idle, etc, etc, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
322 etc. Various things happen depending on the new state of the buddy. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
323 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
324 struct buddy has a member, present, which is set to either 0, 1, or |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
325 2. You can check if the buddy is online with "if (b->present)". This |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
326 becomes important. present is set to either 0 or 1 by serv_got_update, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
327 or is not set at all. When the buddy is passed to set_buddy, if present |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
328 is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
329 to indicate it has already received notification of arrival. It then |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
330 does other signin-related stuff: setting the pixmap to the login icon; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
331 updating the conversation windows; etc. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
332 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
333 The most important thing it does though, if a buddy is present, is it |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
334 checks for the existance of the appropriate group_show and buddy_show for |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
335 that buddy. Each buddy must belong to a group. group_shows are based on |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
336 name; there can only be one group_show for each group name. buddy_shows |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
337 are based both on name and on group_show; there can only be one buddy_show |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
338 in a group_show for each name. However, there can be two buddy_shows |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
339 with the same name as long as they have different group_shows. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
340 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
341 Each buddy_show has a GList of connections that has registered its related |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
342 buddy as being online. set_buddy makes sure that the connection that it's |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
343 being passed is part of the connlist for the buddy_show associated with |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
344 the struct buddy that it's passed (it helps to know your data structures). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
345 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
346 If a buddy logs off (b->present == 0), and a buddy_show exists for |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
347 that buddy, then set_buddy will play the logoff sound, change the icon, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
348 remove the connection from the connlist for the buddy_show, etc. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
349 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
350 And that's how that works. For the buddy lists, connections own buddies; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
351 for the window, the buddies own the connections. When the buddy_show |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
352 connlist count drops to zero it disappears from existance. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
353 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
354 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
355 PLUGINS |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
356 ======= |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
357 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
358 OK, so you want to load a plugin. You go through whatever UI (you |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
359 can read all about the UI in plugins.c or whereever). You finally get |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
360 to load_plugin, the meat of the plugins stuff (plugins can actually |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
361 call load_plugin themselves to load other plugins). load_plugin |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
362 is passed the full path to the plugin you want to load |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
363 (e.g. /usr/local/lib/gaim/irc.so). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
364 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
365 load_plugin does a few things with that filename. The first is to see |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
366 if you've already loaded that plugin. If you have, load_plugin unloads |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
367 the one that is currently loaded. You might wonder why; it's because |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
368 the same plugin can't be loaded twice. If you call g_module_open on a |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
369 filename twice, both times it will return the same pointer, and both times |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
370 increment the reference count on the GModule * that it returns. This |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
371 means you really do have the same plugin twice, which fucks up the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
372 callback system to no end. So it's better that you can only have it |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
373 loaded once at any given time. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
374 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
375 Now that we're assured that we don't have this particular plugin loaded |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
376 yet, we better load it. g_module_open, baby. Much more portable than |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
377 dlopen(). In fact, for Linux it actually is the equivalent of dlopen() |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
378 (you can read the gmodule source and see for yourself). There's only one |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
379 quirk. It always logically ORs the options you pass with RTLD_GLOBAL, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
380 which means that plugins share symbols. I haven't figured out yet if |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
381 this means just functions or variables too; but in either case make every |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
382 function and variable in your plugin static except for gaim_plugin_*(), |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
383 name(), and description(). It's good coding practice anyway. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
384 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
385 So, assuming we didn't get NULL back from g_module_open, we then make sure |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
386 it's a valid gaim plugin by looking for and calling gaim_plugin_init, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
387 courtesy g_module_symbol (g_module_symbol is actually what's portable |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
388 about gmodule as opposed to dl*; some BSD's require '_' prepended to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
389 symbol names and g_module_symbol guarantees we do The Right Thing). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
390 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
391 Assuming we've found gaim_plugin_init and it hasn't returned non-NULL |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
392 to us, we then add it to our list of plugins and go merrily about our way. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
393 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
394 So when do the callbacks happen?! plugin_event, baby, plugin_event. Any |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
395 time you want to trigger a plugin event simply call plugin_even with the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
396 parameters to be passed to any event handlers and you're set. plugin_event |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
397 then makes sure that any plugins waiting for the event get passed the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
398 arguments properly and passes it on to perl. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
399 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
400 Speaking of perl. If you really want to know how this works, you're |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
401 better off reading X-Chat's documentation of it, because it's better |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
402 than what I could provide. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
403 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
404 |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
405 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
406 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
407 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
408 OK, let's start with the basics. There are users. Each user is contained |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
409 in an aim_user struct, and kept track of in the aim_users GList (GSList?). |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
410 Each aim_user has certain features: a username, a password, and user_info. |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
411 It also has certain options, and the protocol it uses to sign on (kept |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
412 as an int which is #define'd in prpl.h). The way the management of the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
413 users works is, there will (hopefully) only be one user for a given |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
414 screenname/ protocol pair (i.e. you may have two user warmenhoven's, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
415 but they'll both have a different protocol number). |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
416 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
417 Now then, there are protocols that gaim knows about. Each protocol is |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
418 in a prpl struct and kept track of in the protocols GSList. The way the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
419 management of the protocols is, there will only ever be one prpl per |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
420 numeric protocol. Each prpl defines a basic set of functions: login, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
421 logout, send_im, etc. The prpl is responsible not only for handling |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
422 these functions, but also for calling the appropriate serv_got functions |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
423 (e.g. serv_got_update when a buddy comes online/goes offline/goes |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
424 idle/etc). It handles each of these on a per-connection basis. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
425 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
426 So why's it called a PRPL? It stands for PRotocol PLugin. That means |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
427 that it's possible to dynamically add new protocols to gaim. However, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
428 all protocols must be implemented the same way: by using a prpl struct |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
429 and being loaded, regardless of whether they are static or dynamic. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
430 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
431 Here's how struct gaim_connection fits into all of this. At some point |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
432 the User (capitalized to indicate a person and not a name) will try to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
433 sign on one of Their users. serv_login is then called for that user. It |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
434 searches for the prpl that is assigned to that user, and calls that prpl's |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
435 login function, passing it the aim_user struct that is attempting to sign |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
436 on. The prpl is then responsible for seeing that the gaim_connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
437 is created (by calling new_gaim_connection), and registering it as |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
438 being online (by calling account_online and passing it the aim_user and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
439 gaim_connection structs). At that point, the aim_user and gaim_connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
440 structs have pointers to each other, and the gaim_connection struct has |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
441 a pointer to the prpl struct that it is using. The gaim_connections are |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
442 stored in the connections GSList. The way connection management works is, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
443 there will always only be one gaim_connection per user, and the prpl that |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
444 the gaim_connection uses will be constant for the gaim_connection's life. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
445 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
446 So at certain points the User is going to want to do certain things, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
447 like send a message. They must send the message on a connection. So the UI |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
448 figures out which gaim_connection the User want to send a message on (for |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
449 our example), and calls serv_send_im, telling it which gaim_connection to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
450 use, and the necessary information (who to send it to, etc). The serv_ |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
451 function then calls the handler of the prpl of the connection for that |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
452 event (that was way too many prepositions). OK, each prpl has a send_im |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
453 function. Each connection has a prpl. so you call gc->prpl->send_im and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
454 pass it the connection and all the necessary info. And that's how things |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
455 get done. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
456 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
457 I hope some of that made sense. Looking back at it it makes absolutely no |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
458 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost. |