Mercurial > pidgin
annotate HACKING @ 9897:62ccc10573d6
[gaim-migrate @ 10786]
(22:23:18) shx: LSchiere: now one that reports correctly when the server
buddy list is full
committer: Tailor Script <tailor@pidgin.im>
author | Luke Schierer <lschiere@pidgin.im> |
---|---|
date | Sat, 28 Aug 2004 02:42:08 +0000 |
parents | db62420a53a2 |
children | 32467b63f55a |
rev | line source |
---|---|
6797 | 1 The majority of the below was written by Eric Warmenhoven way back in |
2 antiquity. I have taken the liberty of attempting to PARTIALLY update | |
3 it. I still think its helpful, but use it at your own risk. | |
4 --Luke | |
5 | |
6 | |
639 | 7 A lot of people have tried to hack gaim, but haven't been able to because |
8 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
|
9 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
|
10 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
|
11 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
|
12 files. As an added bonus, I'll try and describe as best I can how multiple |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
13 connections and multiple protocols work. Depending on how much I want to |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
14 avoid my final tomorrow I may even describe other parts of gaim that I |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
15 particularly want to brag about. Hopefully that's enough to get most of |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
16 you going. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
17 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
18 If you don't know how event-driven programs work, stop right now. Gaim |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
19 uses GTK+'s main loop (actually GLib's but I won't talk about how GTK |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
20 works) and uses GLib functions for timeouts and socket notification. If |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
21 you don't know GTK you should go learn that first. |
639 | 22 |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
23 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
|
24 against the absolute latest CVS. I get really annoyed when I get patches |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
25 against the last released version, especially since I don't usually have |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
26 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
|
27 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
|
28 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
|
29 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
|
30 run the following commands: |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
31 |
9239 | 32 $ export CVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gaim |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
33 $ cvs login (hit enter as the password) |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
34 $ cvs co gaim (you'll see it getting all of the files) |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
35 $ cd gaim |
1863
bf2434d36e54
[gaim-migrate @ 1873]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1710
diff
changeset
|
36 $ ./autogen.sh |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
37 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
38 You'll now have your normal gaim tree with ./configure and all (which |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
39 ./autogen.sh takes the liberty of running for you). (If you want to make |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
40 your life really simple, learn how CVS works. CVS is your friend.) To make |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
41 a patch, just edit the files right there in that tree (don't bother with |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
42 two trees, or even two copies of the same file). Then when you're ready to |
8622 | 43 make your patch, simply run 'cvs diff -u >my.patch' and post it on |
44 sf.net/projects/gaim in the patches section. | |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
45 |
6797 | 46 Some Documentation is available on the Gaim api if you run the command |
47 $make docs | |
48 after running ./configure (or ./autogen.sh). You will need doxygen and | |
49 graphiz dot to generate these docs. | |
2144
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
50 |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
51 CODING STYLE |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
52 ============ |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
53 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
54 Coding styles are like assholes, everyone has one and no one likes anyone |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
55 elses. This is mine and if you want me to accept a patch from you without |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
56 getting annoyed you'll follow this coding style. :) |
2144
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
57 |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
58 It would probably just be easier for me to include CodingStyle from the |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
59 linux kernel source. |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
60 |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
61 Tab indents. I *HATE* 2-space indents, and I strongly dislike 8-space |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
62 indents. Use a tab character. I'm likely to refuse a patch if it has |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
63 2-space indents. |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
64 |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
65 K&R style for braces. Braces always go on the same line as the if, etc. |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
66 that they're associated with; the only exception is functions. Braces |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
67 for else statements should have both braces on the same line as the else |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
68 (i.e. "} else {"). |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
69 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
70 No functionOrVariableNamesLikeThis. Save it for Java. Underscores are your |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
71 friend. "tmp" is an excellent variable name. Hungarian style will not be |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
72 tolerated. Go back to Microsoft. |
2144
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
73 |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
74 I have a 105-char wide Eterm. Deal with it. |
a9940cdb86ee
[gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1863
diff
changeset
|
75 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
76 NO goto. I'm very likely to refuse a patch if it makes use of goto. If you |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
77 feel the need to use goto, you need to rethink your design and flow. |
684
b29c92be568b
[gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
639
diff
changeset
|
78 |
639 | 79 |
6797 | 80 PROGRAM FLOW (just about every function name from here on down is wrong. |
81 ============ but many of the ideas still apply under different names.) | |
639 | 82 |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
83 Before gaim does anything you can see, it initializes itself, which is |
6797 | 84 mostly just reading ~/.gaim/*.xml (handled by the functions in prefs.[ch]) |
85 and parsing command-line options. It then draws the login window by | |
86 calling show_login, and waits for input. | |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
87 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
88 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
|
89 called. This then displays all of the users and various information |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
90 about them. (Don't ask about what happens when "Sign On" is called. It's |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
91 quite hackish. The only reason the login window is there anymore is to |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
92 make it more palatable to people so used to WinAIM that they can't accept |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
93 anything else.) |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
94 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
95 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
|
96 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
|
97 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
|
98 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
|
99 before calling serv_login. serv_login then signs in the user using the |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
100 appropriate protocol. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
101 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
102 After you're signed in, Gaim draws the buddy list by calling |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
103 show_buddy_list. Assuming the user has a buddy list (all buddy list |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
104 functions are controlled by list.c; when you sign on do_import is called |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
105 and that loads the locally saved list), the protocol calls |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
106 serv_got_update, which sets the information in the appropriate struct |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
107 buddy and then passes it off to set_buddy. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
108 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
109 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
|
110 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
|
111 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
|
112 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
|
113 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
|
114 buddy name, even between connections. (If that's not confusing enough, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
115 wait until I really start describing how the buddy list works.) |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
116 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
117 New connections happen the exact same way as described above. Each |
4491 | 118 gaim_account can have one gaim_connection associated with it. gaim_account |
119 and gaim_connection both have a protocol field. This is kind of confusing: | |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
120 gaim, except for the account editor screen and when the user signs on, |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
121 ignores the user's protocl field, and only uses the connection's protocol |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
122 field. You can change the connection's protocol field once it's created |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
123 and been assigned a PRPL to use to change certain behavior (Oscar does |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
124 this because it handles both AIM and ICQ). I'll talk about the |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
125 gaim_connection struct more later. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
126 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
127 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
|
128 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
|
129 open (checked by calling find_conversation), show_conv is called to |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
130 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
|
131 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
|
132 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
133 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
|
134 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
|
135 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK. |
639 | 136 |
137 | |
6797 | 138 SOURCE FILES (this should probly be utterly removed) |
639 | 139 ============ |
140 | |
141 about.c: | |
142 Not much to say here, just a few basic functions. | |
143 | |
6809 | 144 account.[ch]: |
145 This controls the GaimAccount struct, which stores information | |
146 on each account a user registers with gaim. Usernames, pass- | |
147 words, user info, alias, user specific options, and everything | |
7531 | 148 else controlled from within the account editor (and then some) |
6809 | 149 are handled via this code. |
150 | |
151 accountopt.[ch]: | |
152 Api and implemenation for account options. I'm not precisely | |
153 sure how this meshes with account.[ch] | |
7527 | 154 |
639 | 155 away.c: |
156 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
|
157 (do_away_message); coming back (do_im_back); drawing the away window; |
1558
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
158 etc. Away messages work really oddly due to multiple connections and |
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
159 multiple protocols; I think there are really only two or three people |
1619
0bdc891164ad
[gaim-migrate @ 1629]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1558
diff
changeset
|
160 who know how it works and I don't think any of us know why it works |
1558
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
161 that way. |
639 | 162 |
6809 | 163 blist.[ch]: |
6797 | 164 This takes care of the buddy list backend, the blist.xml file, |
165 importing old buddy list files, and related things like | |
6809 | 166 finding buddies and groups. buddies, contacts, and groups |
7531 | 167 are controlled from these files. |
7527 | 168 |
639 | 169 buddy_chat.c: |
170 This takes care of the buddy chat stuff. This used to be a lot bigger | |
171 until the chat and IM windows got merged in the code. Now it mostly | |
172 just takes care of chat-specific stuff, like ignoring people and | |
173 keeping track of who's in the room. This is also where the chat window | |
174 is created. | |
175 | |
176 conversation.c: | |
177 This is where most of the functions dealing with the IM and chat windows | |
178 are hidden. It tries to abstract things as much as possible, but doesn't | |
179 do a very good job. This is also where things like "Enter sends" and | |
180 "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
|
181 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
|
182 the same function, build_conv_toolbar. |
639 | 183 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
184 core.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
185 This is the start of what will become the main() for gaim-core. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
186 |
9709 | 187 gtkdialogs.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
188 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
|
189 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
|
190 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
|
191 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
|
192 is housed, to import buddy lists. (The actual buddy list parsing code |
2166
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
193 is in util.c for winaim lists and buddy.c for gaim's own lists.) |
639 | 194 |
1558
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
195 gtkimhtml.c: |
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
196 This is gaim's HTML widget. It replaced the old widget, GtkHtml (which |
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
197 was different than GNOME's GtkHTML). It's self-contained (it doesn't |
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
198 use any of gaim's code) and is actually a separate project from gaim |
ab5dd2c7e7f8
[gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1237
diff
changeset
|
199 (but is maintained by Eric). |
639 | 200 |
201 idle.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
202 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
|
203 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
|
204 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
|
205 This also takes care of the auto-away stuff. |
639 | 206 |
4586 | 207 main.c: |
208 This is where the main() function is. It takes care of a lot of the | |
209 initialization stuff, and showing the login window. It's pretty tiny | |
210 and there's not really much to edit in it. This has some of the most | |
211 pointless functions, like gaim_setup, which optionally turns off sounds | |
212 on signon. A lot of this file should actually be part of other files. | |
213 | |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
214 md5.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
215 Oscar, Yahoo, and MSN all require md5 hashing, so better to put it in |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
216 the core than have the same thing in three different places. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
217 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
218 module.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
219 This contains all of the plugin code, except for the UI. This is what |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
220 actually loads the plugins, makes sure they're valid, has the code for |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
221 setting up plugin event handlers, and contains the plugin_event method |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
222 that gaim calls on events. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
223 |
639 | 224 prefs.c: |
6797 | 225 Read the documentation on this file. This handles the backend |
7527 | 226 side of prefs. |
639 | 227 |
228 proxy.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
229 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
|
230 now everything actually works. The main function is proxy_connect, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
231 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
|
232 at all) and passes off the data to the appropriate function. This file |
7527 | 233 should be pretty straight-forward. |
234 Except I STRONGLY suspect that time has broken this file. | |
639 | 235 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
236 prpl.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
237 This file is what lets gaim dynamically load protocols, sort of. All |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
238 of the actual dlopen(), dlsym() stuff is in module.c. But this contains |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
239 all of the functions that the protocol plugin needs to call, and manages |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
240 all of the protocols. It's a pretty simple file actually. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
241 |
639 | 242 server.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
243 This is where all of the differentiation between the different protocols |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
244 is done. Nearly everything that's network related goes through here |
639 | 245 at one point or another. This has good things like serv_send_im and |
246 serv_got_update. Most of it should be pretty self-explanatory. | |
247 | |
248 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
249 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
|
250 (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
|
251 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
|
252 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
|
253 and which file should be played. |
639 | 254 |
4586 | 255 util.c: |
256 There's not really a lot of cohesion to this file; it's just a lot of | |
257 stuff that happened to be thrown into it for no apparent reason. None | |
258 of it is particularly tasty; it's all just utility functions. Just | |
259 like the name says. | |
260 | |
261 plugins/ticker/gtkticker.c: | |
262 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that | |
263 widget. It's cool, and it's tiny. This is actually a really good example | |
264 widget for those of you looking to write your own. | |
265 | |
266 plugins/ticker/ticker.c: | |
639 | 267 Syd is just so cool. I really can't get over it. He let me come |
268 visit him at Netscape one day, and I got to see all of their toys | |
269 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
270 ticker. This is also a damn cool file because it's got all of the | |
271 functions that you'd want right up at the top. Someday I want to be | |
272 as cool as Syd. | |
273 | |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
274 For the PRPLs, the only protocol whose "main" gaim file isn't the same as |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
275 the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
276 deprecated and you should be using Oscar for ICQ anyway. |
1653
7fc1a25e567b
[gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1619
diff
changeset
|
277 |
6797 | 278 PLUGINS (read the plugins howto, this is really out of date) |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
279 ======= |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
280 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
281 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
|
282 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
|
283 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
|
284 call load_plugin themselves to load other plugins). load_plugin |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
285 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
|
286 (e.g. /usr/local/lib/gaim/irc.so). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
287 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
288 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
|
289 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
|
290 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
|
291 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
|
292 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
|
293 increment the reference count on the GModule * that it returns. This |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
294 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
|
295 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
|
296 loaded once at any given time. |
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 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
|
299 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
|
300 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
|
301 (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
|
302 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
|
303 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
|
304 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
|
305 function and variable in your plugin static except for gaim_plugin_*(), |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
306 name(), and description(). It's good coding practice anyway. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
307 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
308 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
|
309 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
|
310 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
|
311 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
|
312 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
|
313 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
314 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
|
315 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
|
316 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
317 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
|
318 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
|
319 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
|
320 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
|
321 arguments properly and passes it on to perl. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
322 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
323 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
|
324 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
|
325 than what I could provide. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
326 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
327 |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
328 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
329 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
330 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
331 OK, let's start with the basics. There are users. Each user is contained |
4491 | 332 in an gaim_account struct, and kept track of in the gaim_accounts GSList. |
333 Each gaim_account has certain features: a username, a password, and | |
334 user_info. It also has certain options, and the protocol it uses to sign | |
335 on (kept as an int which is #define'd in prpl.h). | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
336 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
337 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
|
338 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
|
339 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
|
340 numeric protocol. Each prpl defines a basic set of functions: login, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
341 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
|
342 these functions, but also for calling the appropriate serv_got functions |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
343 (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
|
344 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
|
345 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
346 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
|
347 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
|
348 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
|
349 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
|
350 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
351 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
|
352 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
|
353 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
|
354 searches for the prpl that is assigned to that user, and calls that prpl's |
4491 | 355 login function, passing it the gaim_account struct that is attempting to |
356 sign on. The prpl is then responsible for seeing that the gaim_connection | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
357 is created (by calling new_gaim_connection), and registering it as |
4491 | 358 being online (by calling account_online and passing it the gaim_account and |
359 gaim_connection structs). At that point, the gaim_account and gaim_connection | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
360 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
|
361 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
|
362 stored in the connections GSList. The way connection management works is, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
363 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
|
364 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
|
365 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
366 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
|
367 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
|
368 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
|
369 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
|
370 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
|
371 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
|
372 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
|
373 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
|
374 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
|
375 get done. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
376 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
377 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
|
378 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost. |
2166
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
379 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
380 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
381 WRITING PRPLS |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
382 ============= |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
383 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
384 Start off with a protocol that you want to implement; make sure it has a |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
385 number defined in prpl.h. If it doesn't, talk to Rob or Eric about adding |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
386 it. *NEVER* use an unassigned number, not even for testing or personal |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
387 use. It's possible that number will be used later by something else and |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
388 that would cause quite a few head-scratchers. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
389 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
390 Start off with the following boiler plate: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
391 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
392 static struct prpl *my_protocol = NULL; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
393 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
394 void newproto_init(struct prpl *ret) { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
395 ret->protocol = PROTO_NEWPROTO; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
396 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
397 my_protocol = ret; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
398 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
399 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
400 #ifndef STATIC |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
401 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
402 char *gaim_plugin_init(GModule *handle) |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
403 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
404 load_protocol(newproto_init, sizeof(struct prpl)); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
405 return NULL; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
406 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
407 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
408 void gaim_plugin_remove() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
409 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
410 struct prpl *p = find_prpl(PROTO_NEWPROTO); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
411 if (p == my_protocol) |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
412 unload_protocol(p); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
413 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
414 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
415 char *name() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
416 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
417 return "New Protocol"; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
418 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
419 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
420 char *description() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
421 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
422 return PRPL_DESC("New Protocol"); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
423 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
424 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
425 #endif |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
426 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
427 Replace all NEWPROTO things with your protocol name (e.g. PROTO_OSCAR |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
428 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
429 populate your struct prpl; the most important function is actually name(), |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
430 because without it, Gaim will most likely segfault. The second most |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
431 important function is login(). Not all functions need to be implemented. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
432 |
2166
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
433 There should be absolutely *ZERO* GTK in the PRPLs. PRPLs should *NEVER* |
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
434 say what the UI *looks* like, only what information needs to be there. |
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
435 There's currently an effort to get the GTK that is contained in the PRPLs |
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
436 directory out of there. If you submit a patch that adds GTK to those |
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
437 directories it's very likely to be refused, unless if I'm in a good mood |
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
438 and decide to relocate things for you. That's not likely. |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
439 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
440 You're probably wondering how you can do certain things without GTK. Well, |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
441 you're just going to have to make do. Rely on the UI, that's why it's |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
442 there. A PRPL should have absolutely ZERO interaction with the user, it |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
443 should all be handled by the UI. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
444 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
445 Don't use the _options variables at all. The core should take care of all |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
446 of that. There are several proto_opt fields that you can use on a per-user |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
447 basis. Check out existing protocols for more details. |