annotate HACKING @ 7166:e6b01bd8d6cd

[gaim-migrate @ 7733] I fixed the notify_added function, Chip had two of the variables swapped :-) I changed the way tlvlists are done in ssi.c a little bit. You can alias ICQ buddies that you don't have authorization for yet, and when you alias a buddy you will no longer lose any Buddy Alerts that may be set. Why is this? Previously tlvlists (data associated with each server stored item) were just deleted and recreated when you set an alias, or changed your permit/deny setting. Now the lists are modified and TLVs that libfaim doesn't know about are just left in place. Why did I wait so long to do this? I'm lazy, it's not really all that fun, and I don't consider it all that important. committer: Tailor Script <tailor@pidgin.im>
author Mark Doliner <mark@kingant.net>
date Sun, 05 Oct 2003 22:41:29 +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.