annotate HACKING @ 13392:e132f0969763

[gaim-migrate @ 15765] The timestamp plugin shouldn't be disabling the "Gaim timestamps" in this way. It causes the Show Timestamps item in the conversation window's Options menu to not reflect reality (i.e. the option is checked, but no timestamps show up). I think that users can just use the Show Timestamps option to control that setting independently. If people really want this plugin to force timestamps off, it should do so by setting "/gaim/gtk/conversations/show_timestamps" to FALSE and greying out the Show Timestamps menu item. I think this fixes SF Bug #1385439. (It does if they were using this plugin.) committer: Tailor Script <tailor@pidgin.im>
author Richard Laager <rlaager@wiktel.com>
date Sat, 04 Mar 2006 20:18:34 +0000
parents 9f793948154a
children c4a5d8950d8c d88f0f320c9b
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
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
31 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
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
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
34 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
35 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
36 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
37 run the following commands:
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
38
9239
3434d420fe69 [gaim-migrate @ 10038]
Ethan Blanton <elb@pidgin.im>
parents: 8622
diff changeset
39 $ export CVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gaim
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
40 $ cvs login (hit enter as the password)
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
41 $ 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
42 $ cd gaim
1863
bf2434d36e54 [gaim-migrate @ 1873]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1710
diff changeset
43 $ ./autogen.sh
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
44
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
45 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
46 ./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
47 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
48 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
49 two trees, or even two copies of the same file). Then when you're ready to
8622
ffed55cbdd67 [gaim-migrate @ 9373]
Mark Doliner <mark@kingant.net>
parents: 7531
diff changeset
50 make your patch, simply run 'cvs diff -u >my.patch' and post it on
ffed55cbdd67 [gaim-migrate @ 9373]
Mark Doliner <mark@kingant.net>
parents: 7531
diff changeset
51 sf.net/projects/gaim in the patches section.
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
52
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
53 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
54 $make docs
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
55 after running ./configure (or ./autogen.sh). You will need doxygen and
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
56 graphiz dot to generate these docs.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
57
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
58 CODING STYLE
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
59 ============
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
60
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
61 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
62 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
63 getting annoyed you'll follow this coding style. :)
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
64
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
65 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
66 linux kernel source.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
67
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
68 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
69 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
70 2-space indents.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
71
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
72 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
73 that they're associated with; the only exception is functions. Braces
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
74 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
75 (i.e. "} else {").
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 functionOrVariableNamesLikeThis. Save it for Java. Underscores are your
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
78 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
79 tolerated. Go back to Microsoft.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
80
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
81 I have a 105-char wide Eterm. Deal with it.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
82
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
83 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
84 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
85
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
86
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
87 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
88 ============ but many of the ideas still apply under different names.)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
89
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
90 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
91 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
92 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
93 calling show_login, and waits for input.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
94
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
95 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
96 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
97 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
98 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
99 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
100 anything else.)
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
101
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
102 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
103 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
104 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
105 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
106 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
107 appropriate protocol.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
108
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
109 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
110 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
111 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
112 and that loads the locally saved list), the protocol calls
10011
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
113 gaim_prpl_got functions, which set the information in the appropriate
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
114 struct buddy and then passes it off to set_buddy.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
115
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
116 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
117 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
118 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
119 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
120 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
121 buddy name, even between connections. (If that's not confusing enough,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
122 wait until I really start describing how the buddy list works.)
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
123
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
124 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
125 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
126 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
127 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
128 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
129 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
130 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
131 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
132 gaim_connection struct more later.
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 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
135 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
136 open (checked by calling find_conversation), show_conv is called to
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
137 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
138 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
139
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
140 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
141 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
142 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
143
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
144
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
145 SOURCE FILES (this should probly be utterly removed)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
146 ============
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
147
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
148 about.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
149 Not much to say here, just a few basic functions.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
150
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
151 account.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
152 This controls the GaimAccount struct, which stores information
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
153 on each account a user registers with gaim. Usernames, pass-
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
154 words, user info, alias, user specific options, and everything
7531
2c165d32f104 [gaim-migrate @ 8144]
Luke Schierer <lschiere@pidgin.im>
parents: 7527
diff changeset
155 else controlled from within the account editor (and then some)
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
156 are handled via this code.
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
157
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
158 accountopt.[ch]:
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
159 Api and implemenation for account options. I'm not precisely
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
160 sure how this meshes with account.[ch]
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
161
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
162 away.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
163 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
164 (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
165 etc. Away messages work really oddly due to multiple connections and
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
166 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
167 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
168 that way.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
169
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
170 blist.[ch]:
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
171 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
172 importing old buddy list files, and related things like
6809
754afaa07386 [gaim-migrate @ 7349]
Luke Schierer <lschiere@pidgin.im>
parents: 6797
diff changeset
173 finding buddies and groups. buddies, contacts, and groups
7531
2c165d32f104 [gaim-migrate @ 8144]
Luke Schierer <lschiere@pidgin.im>
parents: 7527
diff changeset
174 are controlled from these files.
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
175
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
176 buddy_chat.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
177 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
178 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
179 just takes care of chat-specific stuff, like ignoring people and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
180 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
181 is created.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
182
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
183 conversation.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
184 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
185 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
186 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
187 "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
188 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
189 the same function, build_conv_toolbar.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
190
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
191 core.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
192 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
193
9709
4d05b6e9e9cd [gaim-migrate @ 10570]
Mark Doliner <mark@kingant.net>
parents: 9619
diff changeset
194 gtkdialogs.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
195 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
196 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
197 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
198 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
199 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
200 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
201
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
202 gtkimhtml.c:
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
203 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
204 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
205 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
206 (but is maintained by Eric).
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
207
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
208 idle.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
209 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
210 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
211 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
212 This also takes care of the auto-away stuff.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
213
10320
61852117568f [gaim-migrate @ 11527]
Mark Doliner <mark@kingant.net>
parents: 10011
diff changeset
214 gtkmain.c:
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
215 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
216 initialization stuff, and showing the buddy list or account editor.
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
217
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
218 md5.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
219 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
220 the core than have the same thing in three different places.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
221
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
222 module.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
223 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
224 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
225 setting up plugin event handlers, and contains the plugin_event method
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
226 that gaim calls on events.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
227
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
228 prefs.c:
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
229 Read the documentation on this file. This handles the backend
7527
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
230 side of prefs.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
231
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
232 proxy.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
233 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
234 now everything actually works. The main function is proxy_connect,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
235 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
236 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
237 should be pretty straight-forward.
e64060a18be7 [gaim-migrate @ 8140]
Luke Schierer <lschiere@pidgin.im>
parents: 6809
diff changeset
238 Except I STRONGLY suspect that time has broken this file.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
239
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
240 prpl.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
241 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
242 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
243 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
244 all of the protocols. It's a pretty simple file actually.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
245
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
246 server.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
247 This is where all of the differentiation between the different protocols
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
248 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
249 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
250 it should be pretty self-explanatory.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
251
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
252 sound.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
253 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
254 (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
255 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
256 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
257 and which file should be played.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
258
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
259 util.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
260 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
261 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
262 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
263 like the name says.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
264
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
265 plugins/ticker/gtkticker.c:
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
266 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
267 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
268 widget for those of you looking to write your own.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
269
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
270 plugins/ticker/ticker.c:
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
271 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
272 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
273 (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
274 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
275 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
276 as cool as Syd.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
277
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
278 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
279 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
280 deprecated and you should be using Oscar for ICQ anyway.
1653
7fc1a25e567b [gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1619
diff changeset
281
6797
053b577e08f2 [gaim-migrate @ 7337]
Luke Schierer <lschiere@pidgin.im>
parents: 4586
diff changeset
282 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
283 =======
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
284
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
285 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
286 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
287 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
288 call load_plugin themselves to load other plugins). load_plugin
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
289 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
290 (e.g. /usr/local/lib/gaim/irc.so).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
291
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
292 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
293 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
294 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
295 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
296 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
297 increment the reference count on the GModule * that it returns. This
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
298 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
299 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
300 loaded once at any given time.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
301
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
302 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
303 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
304 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
305 (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
306 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
307 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
308 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
309 function and variable in your plugin static except for gaim_plugin_*(),
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
310 name(), and description(). It's good coding practice anyway.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
311
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
312 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
313 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
314 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
315 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
316 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
317
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
318 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
319 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
320
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
321 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
322 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
323 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
324 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
325 arguments properly and passes it on to perl.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
326
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
327 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
328 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
329 than what I could provide.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
330
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
331
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
332 MULTIPLE CONNECTIONS AND PRPLS
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
333 ==============================
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
334
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
335 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
336 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
337 Each gaim_account has certain features: a username, a password, and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
338 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
339 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
340
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
341 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
342 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
343 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
344 numeric protocol. Each prpl defines a basic set of functions: login,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
345 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
346 these functions, but also for calling the appropriate prpl_got functions
32467b63f55a [gaim-migrate @ 10928]
Mark Doliner <mark@kingant.net>
parents: 9713
diff changeset
347 It handles each of these on a per-account basis.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
348
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
349 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
350 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
351 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
352 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
353
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
354 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
355 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
356 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
357 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
358 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
359 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
360 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
361 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
362 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
363 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
364 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
365 stored in the connections GSList. The way connection management works is,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
366 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
367 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
368
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
369 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
370 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
371 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
372 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
373 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
374 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
375 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
376 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
377 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
378 get done.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
379
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
380 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
381 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
382
2863
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 WRITING PRPLS
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
385 =============
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
386
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
387 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
388 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
389 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
390 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
391 that would cause quite a few head-scratchers.
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 Start off with the following boiler plate:
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 static struct prpl *my_protocol = NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
396
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
397 void newproto_init(struct prpl *ret) {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
398 ret->protocol = PROTO_NEWPROTO;
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 my_protocol = ret;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
401 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
402
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
403 #ifndef STATIC
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 char *gaim_plugin_init(GModule *handle)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
406 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
407 load_protocol(newproto_init, sizeof(struct prpl));
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
408 return NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
409 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
410
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
411 void gaim_plugin_remove()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
412 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
413 struct prpl *p = find_prpl(PROTO_NEWPROTO);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
414 if (p == my_protocol)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
415 unload_protocol(p);
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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
418 char *name()
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 return "New Protocol";
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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
423 char *description()
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 return PRPL_DESC("New Protocol");
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
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
428 #endif
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
429
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
430 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
431 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
432 populate your struct prpl; the most important function is actually name(),
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
433 because without it, Gaim will most likely segfault. The second most
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
434 important function is login(). Not all functions need to be implemented.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
435
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
436 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
437 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
438 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
439 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
440 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
441 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
442
10814
364a2ef907ae [gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents: 10320
diff changeset
443 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
444 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
445 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
446 should all be handled by the UI.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
447
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
448 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
449 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
450 basis. Check out existing protocols for more details.