annotate HACKING @ 14067:f3ed5f4efcae

[gaim-migrate @ 16688] Fix for CID 110 (which also will fix some asserts that happen when you edit your Jabber User Info for the first time) Fix for CID 251 (Null check after deref) Fixes for CID 252, 253. (UNUSED_VALUE) I also changed the jabber_buddy_find() call in jabber_vcard_parse not to create the JabberBuddy if it doesn't exist - there should be a specific jabber buddy attached to the JabberBuddyInfo and if isn't present any more, we shouldn't create a new one. committer: Tailor Script <tailor@pidgin.im>
author Daniel Atallah <daniel.atallah@gmail.com>
date Thu, 10 Aug 2006 21:08:00 +0000
parents c4a5d8950d8c
children d73ee2690376
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11326
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
1 Lots of this is pretty grossly out of date...
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
2 Some of it might still be useful. For coding style, your
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
3 best bet is to browse through some of the files in src and
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
4 emulate what you see there.
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
5 --Mark
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
6
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
7
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
8 The majority of the below was written by Eric Warmenhoven way back in
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
9 antiquity. I have taken the liberty of attempting to PARTIALLY update
11326
9f793948154a [gaim-migrate @ 13537]
Mark Doliner <mark@kingant.net>
parents: 10814
diff changeset
10 it. I still think its helpful, but use it at your own risk.
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
11 --Luke
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
12
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
13
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14 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
15 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
16 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
17 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
18 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
19 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
20 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
21 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
22 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
23 you going.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
24
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
25 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
26 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
27 works) and uses GLib functions for timeouts and socket notification. If
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
28 you don't know GTK+ you should go learn that first.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
29
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
30 If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
31 against the absolute latest SVN. I get really annoyed when I get patches
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
32 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
33 a copy of it on my computer, and gaim tends to change a lot between
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
34 versions. (I sometimes get annoyed when they're against SVN from 3 days
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
35 ago, but can't complain because it's usually my fault that I haven't
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
36 looked at the patch yet.) To get gaim from SVN (if you haven't already),
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
37 run the following commands:
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
38
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
39 $ svn co https://svn.sourceforge.net/svnroot/gaim/trunk gaim
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
40 $ cd gaim
1863
bf2434d36e54 [gaim-migrate @ 1873]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1710
diff changeset
41 $ ./autogen.sh
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
42
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
43 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
44 ./autogen.sh takes the liberty of running for you). (If you want to make
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
45 your life really simple, learn how SVN works. SVN is your friend.) To make
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
46 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
47 two trees, or even two copies of the same file). Then when you're ready to
13632
c4a5d8950d8c [gaim-migrate @ 16030]
Mark Doliner <mark@kingant.net>
parents: 11326
diff changeset
48 make your patch, simply run 'svn diff > my.patch' and post it on
8622
ffed55cbdd67 [gaim-migrate @ 9373]
Mark Doliner <mark@kingant.net>
parents: 7531
diff changeset
49 sf.net/projects/gaim in the patches section.
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
50
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
51 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
52 $make docs
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
53 after running ./configure (or ./autogen.sh). You will need doxygen and
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
54 graphiz dot to generate these docs.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
55
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
56 CODING STYLE
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
57 ============
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
58
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
59 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
60 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
61 getting annoyed you'll follow this coding style. :)
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
62
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
63 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
64 linux kernel source.
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 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
67 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
68 2-space indents.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
69
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
70 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
71 that they're associated with; the only exception is functions. Braces
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
72 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
73 (i.e. "} else {").
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
74
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
75 No functionOrVariableNamesLikeThis. Save it for Java. Underscores are your
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
76 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
77 tolerated. Go back to Microsoft.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
78
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
79 I have a 105-char wide Eterm. Deal with it.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
80
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
81 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
82 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
83
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
84
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
85 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
86 ============ but many of the ideas still apply under different names.)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
87
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
88 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
89 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
90 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
91 calling show_login, and waits for input.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
92
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
93 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
94 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
95 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
96 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
97 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
98 anything else.)
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
99
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
100 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
101 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
102 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
103 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
104 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
105 appropriate protocol.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
106
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
107 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
108 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
109 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
110 and that loads the locally saved list), the protocol calls
10011
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
111 gaim_prpl_got functions, which set the information in the appropriate
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
112 struct buddy and then passes it off to set_buddy.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
113
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
114 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
115 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
116 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
117 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
118 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
119 buddy name, even between connections. (If that's not confusing enough,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
120 wait until I really start describing how the buddy list works.)
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
121
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
122 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
123 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
124 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
125 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
126 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
127 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
128 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
129 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
130 gaim_connection struct more later.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
131
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
132 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
133 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
134 open (checked by calling find_conversation), show_conv is called to
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
135 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
136 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
137
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
138 That's pretty much it for the quick tutorial. I know it wasn't much but
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
139 it's enough to get you started. Make sure you know GTK+ before you get too
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
140 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
141
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
142
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
143 SOURCE FILES (this should probly be utterly removed)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
144 ============
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
145
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
146 about.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
147 Not much to say here, just a few basic functions.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
148
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
149 account.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
150 This controls the GaimAccount struct, which stores information
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
151 on each account a user registers with gaim. Usernames, pass-
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
152 words, user info, alias, user specific options, and everything
7531
2c165d32f104 [gaim-migrate @ 8144]
Luke Schierer <lschiere@pidgin.im>
parents: 7527
diff changeset
153 else controlled from within the account editor (and then some)
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
154 are handled via this code.
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
155
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
156 accountopt.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
157 Api and implemenation for account options. I'm not precisely
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
158 sure how this meshes with account.[ch]
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
159
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
160 away.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
161 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
162 (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
163 etc. Away messages work really oddly due to multiple connections and
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
164 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
165 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
166 that way.
639
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
7531
2c165d32f104 [gaim-migrate @ 8144]
Luke Schierer <lschiere@pidgin.im>
parents: 7527
diff changeset
172 are controlled from these files.
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
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
9709
4d05b6e9e9cd [gaim-migrate @ 10570]
Mark Doliner <mark@kingant.net>
parents: 9619
diff changeset
192 gtkdialogs.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
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
200 gtkimhtml.c:
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
201 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
202 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
203 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
204 (but is maintained by Eric).
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
205
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
206 idle.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
207 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
208 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
209 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
210 This also takes care of the auto-away stuff.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
211
10320
61852117568f [gaim-migrate @ 11527]
Mark Doliner <mark@kingant.net>
parents: 10011
diff changeset
212 gtkmain.c:
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
213 This is where the main() function is. It takes care of a lot of the
10320
61852117568f [gaim-migrate @ 11527]
Mark Doliner <mark@kingant.net>
parents: 10011
diff changeset
214 initialization stuff, and showing the buddy list or account editor.
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
215
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
216 md5.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
217 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
218 the core than have the same thing in three different places.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
219
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
220 module.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
221 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
222 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
223 setting up plugin event handlers, and contains the plugin_event method
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
224 that gaim calls on events.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
225
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
226 prefs.c:
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
227 Read the documentation on this file. This handles the backend
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
228 side of prefs.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
229
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
230 proxy.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
231 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
232 now everything actually works. The main function is proxy_connect,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
233 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
234 at all) and passes off the data to the appropriate function. This file
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
235 should be pretty straight-forward.
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
236 Except I STRONGLY suspect that time has broken this file.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
237
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
238 prpl.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
239 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
240 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
241 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
242 all of the protocols. It's a pretty simple file actually.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
243
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
244 server.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
245 This is where all of the differentiation between the different protocols
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
246 is done. Nearly everything that's network related goes through here
10011
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
247 at one point or another. This has good things like serv_send_im. Most of
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
248 it should be pretty self-explanatory.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
249
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
250 sound.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
251 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
252 (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
253 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
254 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
255 and which file should be played.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
256
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
257 util.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
258 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
259 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
260 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
261 like the name says.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
262
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
263 plugins/ticker/gtkticker.c:
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
264 Syd, our resident GTK+ God, wrote a GtkWidget, GtkTicker. This is that
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
265 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
266 widget for those of you looking to write your own.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
267
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
268 plugins/ticker/ticker.c:
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
269 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
270 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
271 (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
272 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
273 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
274 as cool as Syd.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
275
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
276 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
277 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
278 deprecated and you should be using Oscar for ICQ anyway.
1653
7fc1a25e567b [gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1619
diff changeset
279
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
280 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
281 =======
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
282
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
283 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
284 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
285 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
286 call load_plugin themselves to load other plugins). load_plugin
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
287 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
288 (e.g. /usr/local/lib/gaim/irc.so).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
289
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
290 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
291 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
292 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
293 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
294 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
295 increment the reference count on the GModule * that it returns. This
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
296 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
297 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
298 loaded once at any given time.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
299
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
300 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
301 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
302 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
303 (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
304 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
305 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
306 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
307 function and variable in your plugin static except for gaim_plugin_*(),
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
308 name(), and description(). It's good coding practice anyway.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
309
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
310 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
311 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
312 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
313 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
314 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
315
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
316 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
317 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
318
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
319 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
320 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
321 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
322 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
323 arguments properly and passes it on to perl.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
324
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
325 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
326 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
327 than what I could provide.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
328
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
329
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
330 MULTIPLE CONNECTIONS AND PRPLS
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
331 ==============================
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
332
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
333 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
334 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
335 Each gaim_account has certain features: a username, a password, and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
336 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
337 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
338
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
339 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
340 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
341 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
342 numeric protocol. Each prpl defines a basic set of functions: login,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
343 logout, send_im, etc. The prpl is responsible not only for handling
10011
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
344 these functions, but also for calling the appropriate prpl_got functions
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
345 It handles each of these on a per-account basis.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
346
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
347 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
348 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
349 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
350 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
351
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
352 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
353 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
354 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
355 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
356 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
357 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
358 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
359 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
360 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
361 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
362 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
363 stored in the connections GSList. The way connection management works is,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
364 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
365 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
366
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
367 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
368 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
369 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
370 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
371 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
372 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
373 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
374 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
375 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
376 get done.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
377
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
378 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
379 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
380
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
381
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
382 WRITING PRPLS
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
383 =============
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
384
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
385 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
386 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
387 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
388 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
389 that would cause quite a few head-scratchers.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
390
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
391 Start off with the following boiler plate:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
392
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
393 static struct prpl *my_protocol = NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
394
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
395 void newproto_init(struct prpl *ret) {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
396 ret->protocol = PROTO_NEWPROTO;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
397
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
398 my_protocol = ret;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
399 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
400
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
401 #ifndef STATIC
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
402
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
403 char *gaim_plugin_init(GModule *handle)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
404 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
405 load_protocol(newproto_init, sizeof(struct prpl));
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
406 return NULL;
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 void gaim_plugin_remove()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
410 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
411 struct prpl *p = find_prpl(PROTO_NEWPROTO);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
412 if (p == my_protocol)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
413 unload_protocol(p);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
414 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
415
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
416 char *name()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
417 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
418 return "New Protocol";
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
419 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
420
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
421 char *description()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
422 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
423 return PRPL_DESC("New Protocol");
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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
426 #endif
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
427
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
428 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
429 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
430 populate your struct prpl; the most important function is actually name(),
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
431 because without it, Gaim will most likely segfault. The second most
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
432 important function is login(). Not all functions need to be implemented.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
433
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
434 There should be absolutely *ZERO* GTK+ in the PRPLs. PRPLs should *NEVER*
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
435 say what the UI *looks* like, only what information needs to be there.
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
436 There's currently an effort to get the GTK+ that is contained in the PRPLs
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
437 directory out of there. If you submit a patch that adds GTK+ to those
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
438 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
439 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
440
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
441 You're probably wondering how you can do certain things without GTK+. Well,
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
442 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
443 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
444 should all be handled by the UI.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
445
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
446 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
447 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
448 basis. Check out existing protocols for more details.