annotate HACKING @ 7467:f9ed27be344e

[gaim-migrate @ 8080] this should prevent SSL segfaults when you cancel connections before any SSL magic happens committer: Tailor Script <tailor@pidgin.im>
author Nathan Walp <nwalp@pidgin.im>
date Sun, 09 Nov 2003 08:49:16 +0000
parents 754afaa07386
children e64060a18be7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
1 The majority of the below was written by Eric Warmenhoven way back in
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
2 antiquity. I have taken the liberty of attempting to PARTIALLY update
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
3 it. I still think its helpful, but use it at your own risk.
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
4 --Luke
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
5
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
6
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
7 A lot of people have tried to hack gaim, but haven't been able to because
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
774
b61607d6c2af [gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 749
diff changeset
32 $ export CVSROOT=:pserver:anonymous@cvs.gaim.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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
43 make your patch, simply run 'cvs diff -u >my.patch' and send it off;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
44 either post it on sf.net/projects/gaim in the patches section, or email it
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
45 to gaim@marko.net.
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
46
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
47 Some Documentation is available on the Gaim api if you run the command
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
48 $make docs
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
49 after running ./configure (or ./autogen.sh). You will need doxygen and
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
50 graphiz dot to generate these docs.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
51
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
52 CODING STYLE
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
53 ============
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
54
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
55 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
56 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
57 getting annoyed you'll follow this coding style. :)
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
58
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
59 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
60 linux kernel source.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
61
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
62 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
63 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
64 2-space indents.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
65
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
66 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
67 that they're associated with; the only exception is functions. Braces
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
68 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
69 (i.e. "} else {").
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
70
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
71 No functionOrVariableNamesLikeThis. Save it for Java. Underscores are your
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
72 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
73 tolerated. Go back to Microsoft.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
74
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
75 I have a 105-char wide Eterm. Deal with it.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
76
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
77 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
78 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
79
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
80
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
81 PROGRAM FLOW (just about every function name from here on down is wrong.
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
82 ============ but many of the ideas still apply under different names.)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
83
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
84 Before gaim does anything you can see, it initializes itself, which is
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
85 mostly just reading ~/.gaim/*.xml (handled by the functions in prefs.[ch])
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
86 and parsing command-line options. It then draws the login window by
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
87 calling show_login, and waits for input.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
88
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
89 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
90 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
91 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
92 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
93 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
94 anything else.)
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
95
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
96 When the "Sign on/off" button is clicked, serv_login is passed the
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
97 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
98 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
99 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
100 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
101 appropriate protocol.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
102
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
103 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
104 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
105 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
106 and that loads the locally saved list), the protocol calls
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
107 serv_got_update, which sets the information in the appropriate struct
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
108 buddy and then passes it off to set_buddy.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
109
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
110 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
111 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
112 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
113 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
114 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
115 buddy name, even between connections. (If that's not confusing enough,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
116 wait until I really start describing how the buddy list works.)
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
117
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
118 New connections happen the exact same way as described above. Each
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
119 gaim_account can have one gaim_connection associated with it. gaim_account
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
120 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
121 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
122 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
123 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
124 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
125 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
126 gaim_connection struct more later.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
127
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
128 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
129 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
130 open (checked by calling find_conversation), show_conv is called to
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
131 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
132 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
133
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
134 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
135 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
136 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
137
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
138
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
139 SOURCE FILES (this should probly be utterly removed)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
140 ============
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
141
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
142 about.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
143 Not much to say here, just a few basic functions.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
144
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
145 account.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
146 This controls the GaimAccount struct, which stores information
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
147 on each account a user registers with gaim. Usernames, pass-
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
148 words, user info, alias, user specific options, and everything
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
149 else controled from within the account editor (and then some)
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
150 are handled via this code.
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
151
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
152 accountopt.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
153 Api and implemenation for account options. I'm not precisely
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
154 sure how this meshes with account.[ch]
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
155
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
156 away.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
157 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
158 (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
159 etc. Away messages work really oddly due to multiple connections and
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
160 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
161 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
162 that way.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
163
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
164 browser.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
165 Code for opening a browser window. Most of the code is trying to deal
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
166 with Netscape. The most important function here is open_url. Have fun.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
167
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
168 blist.[ch]:
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
169 This takes care of the buddy list backend, the blist.xml file,
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
170 importing old buddy list files, and related things like
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
171 finding buddies and groups. buddies, contacts, and groups
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
172 are controled from these files.
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
173
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
174 buddy_chat.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
175 This takes care of the buddy chat stuff. This used to be a lot bigger
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
176 until the chat and IM windows got merged in the code. Now it mostly
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
177 just takes care of chat-specific stuff, like ignoring people and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
178 keeping track of who's in the room. This is also where the chat window
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
179 is created.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
180
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
181 conversation.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
182 This is where most of the functions dealing with the IM and chat windows
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
183 are hidden. It tries to abstract things as much as possible, but doesn't
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
184 do a very good job. This is also where things like "Enter sends" and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
185 "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
186 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
187 the same function, build_conv_toolbar.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
188
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
189 core.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
190 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
191
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
192 dialogs.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
193 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
194 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
195 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
196 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
197 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
198 is in util.c for winaim lists and buddy.c for gaim's own lists.)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
199
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
200 gaimrc.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
201 This controls everything about the .gaimrc file. There's not really much
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
202 to say about it; this is probably one of the better designed and easier
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
203 to follow files in gaim. The important functions are towards the bottom.
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
204 This file is also utterly deprecated. It is used only for importing
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
205 on upgrade. the prefs.c and prefs.h files replace the control,
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
206 and gtkprefs.c replaces the gui component.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
207
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
208 gtkimhtml.c:
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
209 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
210 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
211 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
212 (but is maintained by Eric).
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
213
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
214 html.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
215 Don't ask my why this is called html.c. Most of it is just grab_url,
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
216 which does like the name says; it downloads a URL to show in the
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
217 GtkHTML widget. http.c would be a more appropriate name, but that's OK.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
218
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
219 idle.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
220 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
221 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
222 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
223 This also takes care of the auto-away stuff.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
224
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
225 main.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
226 This is where the main() function is. It takes care of a lot of the
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
227 initialization stuff, and showing the login window. It's pretty tiny
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
228 and there's not really much to edit in it. This has some of the most
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
229 pointless functions, like gaim_setup, which optionally turns off sounds
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
230 on signon. A lot of this file should actually be part of other files.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
231
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
232 md5.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
233 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
234 the core than have the same thing in three different places.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
235
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
236 module.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
237 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
238 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
239 setting up plugin event handlers, and contains the plugin_event method
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
240 that gaim calls on events.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
241
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
242 multi.c:
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
243 This is the file that tries to take care of most of the major issues
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
244 with multiple connections. The best function in here by far is the
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
245 account_editor(). auto_login() is also in here (I'm just reading multi.h
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
246 now...). account_editor is really the only function that the UI needs
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
247 to be concerned with.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
248
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
249 prefs.c:
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
250 Read the documentation on this file. This handles the backend
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
251 side of prefs.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
252
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
253 proxy.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
254 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
255 now everything actually works. The main function is proxy_connect,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
256 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
257 at all) and passes off the data to the appropriate function. This file
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
258 should be pretty straight-forward.
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
259 Except I STRONGLY suspect that time has broken this file.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
260
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
261 prpl.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
262 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
263 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
264 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
265 all of the protocols. It's a pretty simple file actually.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
266
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
267 server.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
268 This is where all of the differentiation between the different protocols
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
269 is done. Nearly everything that's network related goes through here
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
270 at one point or another. This has good things like serv_send_im and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
271 serv_got_update. Most of it should be pretty self-explanatory.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
272
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
273 sound.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
274 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
275 (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
276 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
277 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
278 and which file should be played.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
279
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
280 util.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
281 There's not really a lot of cohesion to this file; it's just a lot of
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
282 stuff that happened to be thrown into it for no apparent reason. None
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
283 of it is particularly tasty; it's all just utility functions. Just
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
284 like the name says.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
285
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
286 plugins/ticker/gtkticker.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
287 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
288 widget. It's cool, and it's tiny. This is actually a really good example
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
289 widget for those of you looking to write your own.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
290
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
291 plugins/ticker/ticker.c:
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
292 Syd is just so cool. I really can't get over it. He let me come
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
293 visit him at Netscape one day, and I got to see all of their toys
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
294 (don't worry, I'm under an NDA). Anyway, this file is for the buddy
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
295 ticker. This is also a damn cool file because it's got all of the
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
296 functions that you'd want right up at the top. Someday I want to be
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
297 as cool as Syd.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
298
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
299 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
300 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
301 deprecated and you should be using Oscar for ICQ anyway.
1653
7fc1a25e567b [gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1619
diff changeset
302
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
303 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
304 =======
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
305
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
306 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
307 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
308 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
309 call load_plugin themselves to load other plugins). load_plugin
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
310 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
311 (e.g. /usr/local/lib/gaim/irc.so).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
312
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
313 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
314 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
315 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
316 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
317 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
318 increment the reference count on the GModule * that it returns. This
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
319 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
320 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
321 loaded once at any given time.
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 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
324 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
325 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
326 (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
327 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
328 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
329 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
330 function and variable in your plugin static except for gaim_plugin_*(),
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
331 name(), and description(). It's good coding practice anyway.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
332
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
333 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
334 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
335 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
336 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
337 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
338
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
339 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
340 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
341
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
342 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
343 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
344 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
345 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
346 arguments properly and passes it on to perl.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
347
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
348 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
349 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
350 than what I could provide.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
351
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
352
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
353 MULTIPLE CONNECTIONS AND PRPLS
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
354 ==============================
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
355
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
356 OK, let's start with the basics. There are users. Each user is contained
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
357 in an gaim_account struct, and kept track of in the gaim_accounts GSList.
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
358 Each gaim_account has certain features: a username, a password, and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
359 user_info. It also has certain options, and the protocol it uses to sign
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
360 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
361
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
362 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
363 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
364 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
365 numeric protocol. Each prpl defines a basic set of functions: login,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
366 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
367 these functions, but also for calling the appropriate serv_got functions
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
368 (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
369 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
370
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
371 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
372 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
373 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
374 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
375
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
376 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
377 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
378 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
379 searches for the prpl that is assigned to that user, and calls that prpl's
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
380 login function, passing it the gaim_account struct that is attempting to
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
381 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
382 is created (by calling new_gaim_connection), and registering it as
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
383 being online (by calling account_online and passing it the gaim_account and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
384 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
385 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
386 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
387 stored in the connections GSList. The way connection management works is,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
388 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
389 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
390
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
391 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
392 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
393 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
394 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
395 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
396 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
397 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
398 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
399 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
400 get done.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
401
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
402 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
403 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
404
2863
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 WRITING PRPLS
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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
409 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
410 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
411 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
412 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
413 that would cause quite a few head-scratchers.
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 Start off with the following boiler plate:
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 static struct prpl *my_protocol = NULL;
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 void newproto_init(struct prpl *ret) {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
420 ret->protocol = PROTO_NEWPROTO;
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 my_protocol = ret;
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 #ifndef STATIC
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 char *gaim_plugin_init(GModule *handle)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
428 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
429 load_protocol(newproto_init, sizeof(struct prpl));
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
430 return NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
431 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
432
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
433 void gaim_plugin_remove()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
434 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
435 struct prpl *p = find_prpl(PROTO_NEWPROTO);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
436 if (p == my_protocol)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
437 unload_protocol(p);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
438 }
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 char *name()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
441 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
442 return "New Protocol";
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
443 }
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 char *description()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
446 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
447 return PRPL_DESC("New Protocol");
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
448 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
449
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
450 #endif
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
451
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
452 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
453 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
454 populate your struct prpl; the most important function is actually name(),
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
455 because without it, Gaim will most likely segfault. The second most
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
456 important function is login(). Not all functions need to be implemented.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
457
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
458 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
459 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
460 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
461 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
462 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
463 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
464
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
465 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
466 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
467 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
468 should all be handled by the UI.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
469
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
470 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
471 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
472 basis. Check out existing protocols for more details.