Mercurial > pidgin.yaz
comparison plugins/PERL-HOWTO @ 1101:0ef4386edc29
[gaim-migrate @ 1111]
wow, perl got updated.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Thu, 16 Nov 2000 10:06:12 +0000 |
parents | 67bdecdecbb7 |
children | dd78a230aa06 |
comparison
equal
deleted
inserted
replaced
1100:f168625b63fe | 1101:0ef4386edc29 |
---|---|
1 This is really the wrong place for a HOWTO on writing perl scripts for gaim, | 1 This is really the wrong place for a HOWTO on writing perl scripts for gaim, |
2 but there didn't seem to be a much better place. | 2 but there didn't seem to be a much better place. |
3 | 3 |
4 If you've ever written a perl script for X-Chat then you've basically written | 4 If you've ever written a perl script for X-Chat then you've basically written |
5 one for gaim as well. perl.c in gaim's source is basically an exact copy of | 5 one for gaim as well. perl.c in gaim's source is basically an exact copy of |
6 X-Chat's perl.c file, with small modifications to suit AIM rather than IRC. | 6 X-Chat's perl.c file, with small modifications to suit GAIM rather than IRC. |
7 | 7 |
8 Basically the reason for including perl is based on the experience with the | 8 Basically the reason for including perl is based on the experience with the |
9 plugins. X-Chat's docs on Perl Scripting sums it up nicely: | 9 plugins. X-Chat's docs on Perl Scripting sums it up nicely: |
10 it's not quite as simple to stick a module together in C and make it | 10 it's not quite as simple to stick a module together in C and make it |
11 stable compared to the development time of perl code | 11 stable compared to the development time of perl code |
19 There's a really quick simple perl script in this directory, gaim.pl, that | 19 There's a really quick simple perl script in this directory, gaim.pl, that |
20 should show most of the functions. Most things should be self-explanatory. | 20 should show most of the functions. Most things should be self-explanatory. |
21 | 21 |
22 Everything available in normal perl scripts should be available in gaim's | 22 Everything available in normal perl scripts should be available in gaim's |
23 perl interface, so I'm not going to bother describing that. The important | 23 perl interface, so I'm not going to bother describing that. The important |
24 things are the functions provided by gaim's internal AIM module, which is | 24 things are the functions provided by gaim's internal GAIM module, which is |
25 what most of this document is about. So, onto the functions. | 25 what most of this document is about. So, onto the functions. |
26 | 26 |
27 AIM::register(name, version, shutdownroutine, unused) | 27 GAIM::register(name, version, shutdownroutine, unused) |
28 Just like X-Chat. This is the first function your script should call. | 28 Just like X-Chat. This is the first function your script should call. |
29 shutdownroutine is a function that will be called when the script | 29 shutdownroutine is a function that will be called when the script |
30 gets unloaded (like when gaim gets closed). This function returns | 30 gets unloaded (like when gaim gets closed). This function returns |
31 gaim's version number. | 31 gaim's version number. |
32 | 32 |
33 AIM::get_info(integer) | 33 GAIM::get_info(integer, ...) |
34 This function returns different information based on the integer passed | 34 This function returns different information based on the integer passed |
35 to it. | 35 to it. |
36 0 - the version of gaim you're running ("0.10.0" for example). | 36 0 - the version of gaim you're running ("0.10.0" for example). |
37 1 - the screenname to last attempt to sign on | 37 1 - the list of currently online screennames |
38 2 - either "Offline", "TOC", or "Oscar" | 38 2 - given a screenname, the protocol(s) it(/they) use(s) (as ints) |
39 | 39 |
40 AIM::print(title, message) | 40 GAIM::print(title, message) |
41 This displays a nice little dialog window. | 41 This displays a nice little dialog window. |
42 | 42 |
43 | 43 |
44 AIM::buddy_list() | 44 GAIM::buddy_list(name) |
45 This returns the buddy list (no groups, just the names of the buddies) | 45 This returns the buddy list (no groups, just the names of the buddies) |
46 for the specified account | |
46 | 47 |
47 AIM::online_list() | 48 GAIM::online_list(name) |
48 This returns the list of online buddies. | 49 This returns the list of online buddies for the specified account. |
49 | |
50 AIM::deny_list() | |
51 This returns the deny list. This is probably going to be modified before | |
52 0.10.0 is released to return either the deny or the permit list and the | |
53 current mode. | |
54 | 50 |
55 | 51 |
56 AIM::command(command, ...) | 52 GAIM::command(command, ...) |
57 This sends commands to the server, and each command takes various | 53 This sends commands to the server, and each command takes various |
58 arguments. The command should be self-explanatory: | 54 arguments. The command should be self-explanatory: |
59 "signon" - no args. | 55 "signon" - the second arg is the screenname to sign on |
60 "signoff" - no args. | 56 "signoff" - the optional second arg is who to sign off. if no args are |
57 given, all names are signed off. | |
61 "away" - the second arg is the away message | 58 "away" - the second arg is the away message |
62 "back" - no args. | 59 "back" - no args. |
63 "idle" - the second arg is how long (in seconds) to set the idle time | 60 "idle" - the second arg is how long (in seconds) to set the idle time |
64 "warn" - the second arg is the name of the person to warn | 61 (this sets the idle time for all connections) |
62 "warn" - the second arg is the name of the person to warn. this is | |
63 especially evil since it warns the person from every connection. | |
65 | 64 |
66 AIM::user_info(nick) | 65 GAIM::user_info(nick) |
67 Returns 7 data items: | 66 Returns 8 data items: |
68 the screenname of the buddy | 67 the screenname of the buddy |
68 the alias of the buddy | |
69 "Online" or "Offline" | 69 "Online" or "Offline" |
70 their warning level | 70 their warning level |
71 signon time, in seconds since the epoch | 71 signon time, in seconds since the epoch |
72 idle time, in seconds (?) | 72 idle time, in seconds (?) |
73 user class, an integer with bit values | 73 user class, an integer with bit values |
81 VOICE 2 | 81 VOICE 2 |
82 IMIMAGE 4 | 82 IMIMAGE 4 |
83 CHAT 8 | 83 CHAT 8 |
84 GETFILE 16 | 84 GETFILE 16 |
85 SENDFILE 32 | 85 SENDFILE 32 |
86 Since buddy lists are per-connection this goes through the connections | |
87 until it finds a matching buddy name. | |
86 | 88 |
87 This is probably going to change before 0.10.0 is released to | 89 GAIM::print_to_conv(who, what) |
88 also return the alias of the buddy. | 90 The question is not what does this do, it's who does this do it as. The |
91 answer is "whatever the default is". It uses whichever connection is | |
92 selected in the conversation window's menu. If the conversation window | |
93 didn't exist beforehand, then it's the default (first) connection. | |
89 | 94 |
90 AIM::print_to_conv(who, what) | 95 GAIM::print_to_chat(room, what) |
91 This should be obvious. If you can't figure this out on your own, you | 96 This goes through each connection. If it finds a room matching the name, |
92 shouldn't be using a computer. | 97 it'll print the message to that room. |
93 | |
94 AIM::print_to_chat(room, what) | |
95 This should be just as obvious as the last command. | |
96 | 98 |
97 | 99 |
98 AIM::add_event_handler(event, function) | 100 GAIM::add_event_handler(event, function) |
99 This is the most important of them all. This is basically exactly like | 101 This is the most important of them all. This is basically exactly like |
100 gaim_signal_connect for plugins. You pass which event you want to connect to | 102 gaim_signal_connect for plugins. You pass which event you want to connect to |
101 (a string with the same name as the events for plugins, see SIGNALS), and a | 103 (a string with the same name as the events for plugins, see SIGNALS), and a |
102 string with the name of the function you want called. Simple enough? | 104 string with the name of the function you want called. Simple enough? |
103 | 105 |
104 When this is triggered, the arguments will be passed in @_ and are not | 106 When this is triggered, the arguments will be passed in @_ and are not |
105 broken into a list, but left as one long string. You'll have to parse those | 107 broken into a list, but left as one long string. You'll have to parse those |
106 yourself with split. (Sounding exactly like X-Chat yet?) The arguments are | 108 yourself with split. (Sounding exactly like X-Chat yet?) The arguments are |
107 the exact same as those passed to the plugins, and are passed after the | 109 the exact same as those passed to the plugins, and are passed after the |
108 plugins have had their way with them. Perl scripts cannot modify the values | 110 plugins have had their way with them. Perl scripts cannot modify the values |
109 so that gaim knows what the changes are. Unlike X-Chat, perl scripts cannot | 111 so that gaim knows what the changes are. |
110 short-circut gaim (that is, your script will be called in order it was added, | 112 |
111 despite what other scripts do, and afterwards, execution will continue as | 113 Perl scripts can short-circuit certain events (namely event_im_send, |
112 normal). Names of buddies and chat rooms will be in quotes, and all other | 114 event_im_recv, event_chat_send, and event_chat_recv). To short-circuit an |
115 event simply return a non-0 value. This will cause all subsequent scripts | |
116 and the event itself to never happen (i.e. the user won't see it happen, | |
117 and _send events won't actually send). | |
118 | |
119 Names of buddies and chat rooms will be in quotes, and all other | |
113 values (like text messages) will not be. (Watch the debug window to get a | 120 values (like text messages) will not be. (Watch the debug window to get a |
114 better feel for this, or better yet, look at the bottom of plugins.c.) | 121 better feel for this, or better yet, look at the bottom of plugins.c.) |
115 | 122 |
116 AIM::add_timeout_handler(integer, function) | 123 GAIM::add_timeout_handler(integer, function) |
117 This calls function after integer number of seconds. It only calls function | 124 This calls function after integer number of seconds. It only calls function |
118 once, so if you want to keep calling function, keep readding the handler. | 125 once, so if you want to keep calling function, keep readding the handler. |