Mercurial > pidgin.yaz
annotate HACKING @ 11184:044645e8a679
[gaim-migrate @ 13296]
.cvsignore files are used to "ignore" files that you don't want
in your CVS repository. This typically includes files created
during the build processes, temp files created by editors, etc.
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Wed, 03 Aug 2005 02:59:39 +0000 |
parents | 364a2ef907ae |
children | 9f793948154a |
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 |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
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 |
10011 | 106 gaim_prpl_got functions, which set the information in the appropriate |
107 struct 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 |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
134 it's enough to get you started. Make sure you know GTK+ before you get too |
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
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 |
10320 | 207 gtkmain.c: |
4586 | 208 This is where the main() function is. It takes care of a lot of the |
10320 | 209 initialization stuff, and showing the buddy list or account editor. |
4586 | 210 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
211 md5.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
212 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
|
213 the core than have the same thing in three different places. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
214 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
215 module.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
216 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
|
217 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
|
218 setting up plugin event handlers, and contains the plugin_event method |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
219 that gaim calls on events. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
220 |
639 | 221 prefs.c: |
6797 | 222 Read the documentation on this file. This handles the backend |
7527 | 223 side of prefs. |
639 | 224 |
225 proxy.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
226 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
|
227 now everything actually works. The main function is proxy_connect, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
228 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
|
229 at all) and passes off the data to the appropriate function. This file |
7527 | 230 should be pretty straight-forward. |
231 Except I STRONGLY suspect that time has broken this file. | |
639 | 232 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
233 prpl.c: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
234 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
|
235 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
|
236 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
|
237 all of the protocols. It's a pretty simple file actually. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
238 |
639 | 239 server.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
240 This is where all of the differentiation between the different protocols |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
241 is done. Nearly everything that's network related goes through here |
10011 | 242 at one point or another. This has good things like serv_send_im. Most of |
243 it should be pretty self-explanatory. | |
639 | 244 |
245 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
246 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
|
247 (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
|
248 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
|
249 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
|
250 and which file should be played. |
639 | 251 |
4586 | 252 util.c: |
253 There's not really a lot of cohesion to this file; it's just a lot of | |
254 stuff that happened to be thrown into it for no apparent reason. None | |
255 of it is particularly tasty; it's all just utility functions. Just | |
256 like the name says. | |
257 | |
258 plugins/ticker/gtkticker.c: | |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
259 Syd, our resident GTK+ God, wrote a GtkWidget, GtkTicker. This is that |
4586 | 260 widget. It's cool, and it's tiny. This is actually a really good example |
261 widget for those of you looking to write your own. | |
262 | |
263 plugins/ticker/ticker.c: | |
639 | 264 Syd is just so cool. I really can't get over it. He let me come |
265 visit him at Netscape one day, and I got to see all of their toys | |
266 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
267 ticker. This is also a damn cool file because it's got all of the | |
268 functions that you'd want right up at the top. Someday I want to be | |
269 as cool as Syd. | |
270 | |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
271 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
|
272 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
|
273 deprecated and you should be using Oscar for ICQ anyway. |
1653
7fc1a25e567b
[gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1619
diff
changeset
|
274 |
6797 | 275 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
|
276 ======= |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
277 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
278 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
|
279 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
|
280 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
|
281 call load_plugin themselves to load other plugins). load_plugin |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
282 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
|
283 (e.g. /usr/local/lib/gaim/irc.so). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
284 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
285 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
|
286 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
|
287 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
|
288 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
|
289 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
|
290 increment the reference count on the GModule * that it returns. This |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
291 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
|
292 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
|
293 loaded once at any given time. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
294 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
295 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
|
296 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
|
297 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
|
298 (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
|
299 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
|
300 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
|
301 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
|
302 function and variable in your plugin static except for gaim_plugin_*(), |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
303 name(), and description(). It's good coding practice anyway. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
304 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
305 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
|
306 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
|
307 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
|
308 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
|
309 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
|
310 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
311 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
|
312 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
|
313 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
314 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
|
315 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
|
316 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
|
317 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
|
318 arguments properly and passes it on to perl. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
319 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
320 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
|
321 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
|
322 than what I could provide. |
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 |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
325 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
326 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
327 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
328 OK, let's start with the basics. There are users. Each user is contained |
4491 | 329 in an gaim_account struct, and kept track of in the gaim_accounts GSList. |
330 Each gaim_account has certain features: a username, a password, and | |
331 user_info. It also has certain options, and the protocol it uses to sign | |
332 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
|
333 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
334 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
|
335 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
|
336 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
|
337 numeric protocol. Each prpl defines a basic set of functions: login, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
338 logout, send_im, etc. The prpl is responsible not only for handling |
10011 | 339 these functions, but also for calling the appropriate prpl_got functions |
340 It handles each of these on a per-account basis. | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
341 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
342 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
|
343 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
|
344 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
|
345 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
|
346 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
347 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
|
348 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
|
349 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
|
350 searches for the prpl that is assigned to that user, and calls that prpl's |
4491 | 351 login function, passing it the gaim_account struct that is attempting to |
352 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
|
353 is created (by calling new_gaim_connection), and registering it as |
4491 | 354 being online (by calling account_online and passing it the gaim_account and |
355 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
|
356 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
|
357 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
|
358 stored in the connections GSList. The way connection management works is, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
359 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
|
360 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
|
361 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
362 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
|
363 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
|
364 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
|
365 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
|
366 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
|
367 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
|
368 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
|
369 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
|
370 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
|
371 get done. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
372 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
373 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
|
374 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
|
375 |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
376 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
377 WRITING PRPLS |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
378 ============= |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
379 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
380 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
|
381 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
|
382 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
|
383 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
|
384 that would cause quite a few head-scratchers. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
385 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
386 Start off with the following boiler plate: |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
387 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
388 static struct prpl *my_protocol = NULL; |
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 void newproto_init(struct prpl *ret) { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
391 ret->protocol = PROTO_NEWPROTO; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
392 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
393 my_protocol = ret; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
394 } |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
395 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
396 #ifndef STATIC |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
397 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
398 char *gaim_plugin_init(GModule *handle) |
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 load_protocol(newproto_init, sizeof(struct prpl)); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
401 return NULL; |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
402 } |
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 void gaim_plugin_remove() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
405 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
406 struct prpl *p = find_prpl(PROTO_NEWPROTO); |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
407 if (p == my_protocol) |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
408 unload_protocol(p); |
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 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
411 char *name() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
412 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
413 return "New Protocol"; |
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 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
416 char *description() |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
417 { |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
418 return PRPL_DESC("New Protocol"); |
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 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
421 #endif |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
422 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
423 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
|
424 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
425 populate your struct prpl; the most important function is actually name(), |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
426 because without it, Gaim will most likely segfault. The second most |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
427 important function is login(). Not all functions need to be implemented. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
428 |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
429 There should be absolutely *ZERO* GTK+ in the PRPLs. PRPLs should *NEVER* |
2166
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
430 say what the UI *looks* like, only what information needs to be there. |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
431 There's currently an effort to get the GTK+ that is contained in the PRPLs |
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
432 directory out of there. If you submit a patch that adds GTK+ to those |
2166
dbd74f49dabb
[gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2150
diff
changeset
|
433 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
|
434 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
|
435 |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10320
diff
changeset
|
436 You're probably wondering how you can do certain things without GTK+. Well, |
2863
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
437 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
|
438 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
|
439 should all be handled by the UI. |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
440 |
0e70fe072ab4
[gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2655
diff
changeset
|
441 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
|
442 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
|
443 basis. Check out existing protocols for more details. |