Mercurial > hg
annotate mcabber/doc/HOWTO_modules.txt @ 1915:e09763e16e49
Fix segfault related to url_regex
author | franky |
---|---|
date | Thu, 04 Nov 2010 19:51:02 +0100 |
parents | 3cabdacf58df |
children | e702073612de |
rev | line source |
---|---|
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
1 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
2 =========================================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
3 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
4 Mcabber module writing brief howto |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
5 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
6 =========================================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
7 |
1830 | 8 To obtain information on module mcabber uses struct module_info_t, that |
9 module should provide in public variable with name info_<modulename>. | |
10 If the module name contains any extra symbols except [a-z0-9_] they | |
11 should be replaced with '_'. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
12 |
1830 | 13 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
14 #include <mcabber/modules.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
15 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
16 typedef void (*module_init_t)(void); |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
17 typedef void (*module_uninit_t)(void); |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
18 |
1752 | 19 typedef struct module_info_struct module_info_t; |
20 struct module_info_struct { | |
21 const gchar *branch; | |
22 guint api; | |
23 const gchar *version; | |
24 const gchar *description; | |
1754
d8442bcb33b7
Reorder fields in module info struct
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1752
diff
changeset
|
25 const gchar **requires; |
d8442bcb33b7
Reorder fields in module info struct
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1752
diff
changeset
|
26 module_init_t init; |
d8442bcb33b7
Reorder fields in module info struct
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1752
diff
changeset
|
27 module_uninit_t uninit; |
1752 | 28 module_info_t *next; |
29 }; | |
1830 | 30 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
31 |
1830 | 32 Callbacks init and uninit will be called after module and its |
33 dependencies loading. 'requires' can contain a NULL-terminated list of | |
34 module names, that should be loaded before this. 'branch' and 'api' are | |
35 required and should contain mcabber branch and api version, that this | |
36 module is designed to work with. For these values see ChangeLog.api. | |
37 'version' and 'description' fields are optional and just provide user | |
38 with additional information about the module. 'description' field can | |
39 contain newlines. The 'next' field can contain pointer to the next | |
40 struct with another branch of mcabber, if your module can work with | |
41 multiple branches. | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
42 |
1830 | 43 To load modules, mcabber uses glib's GModule, thus, in your module you |
44 can also use functions | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
45 |
1830 | 46 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
47 #include <glib.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
48 #include <gmodule.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
49 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
50 const gchar* g_module_check_init (GModule *module); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
51 void g_module_unload (GModule *module); |
1830 | 52 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
53 |
1830 | 54 to do something before any version/dependency check is performed when |
55 your module is loaded/unloaded. On success g_module_check_init should | |
56 return NULL, and error message otherwise. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
57 |
1830 | 58 As module is loaded, you can use mcabber functions, declared in |
59 mcabber's header files (though you should consider, that they may change | |
60 their calling conventions some day). | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
61 |
1830 | 62 I will not explain them all, there are too much of them, but will |
63 provide description for those, provided especially for module writers. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
64 |
1830 | 65 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
66 #include <mcabber/modules.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
67 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
68 const gchar *module_load (const gchar *name, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
69 gboolean manual, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
70 gboolean force); |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
71 const gchar *module_unload (const gchar *name, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
72 gboolean manual, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
73 gboolean force); |
1830 | 74 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
75 |
1830 | 76 These functions load and unload modules respectively. You can use them |
77 to handle optional dependencies. What happens, when module is loaded: | |
78 - check if module is present, and if present just increase it's | |
79 reference count | |
80 - load .so via glib (and call g_module_check_init, if present) | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
81 - check for information structure presence |
1830 | 82 - find suitable branch and check api version compatibility |
83 - load modules, that this module requires (note, that dependency | |
84 problems will be reported as error invariably, force flag have no | |
85 effect on this check) | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
86 - module placed into a list of modules |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
87 - module init routine is called |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
88 And when unloaded: |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
89 - check if module is present |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
90 - decrease reference count, if it is not zero, return |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
91 - run module uninit routine |
1830 | 92 - unload modules, that were loaded as dependencies for this one |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
93 - remove from modules list |
1830 | 94 They return error message or NULL in case of success. 'manual' flag |
95 indicates, that module will be loaded by direct user request. It serves | |
96 the purpose of tracking user and automatic references (user can have | |
97 only one). 'force' flag on module loading causes mcabber to ignore most | |
98 of the loading errors. On unload it forces unloading even if reference | |
99 count is not zero. | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
100 |
1830 | 101 ------------------------------------------------------------------------ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
102 #include <mcabber/commands.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
103 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
104 void cmd_add (const char *name, const char *help, |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
105 guint flags1, guint flags2, |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
106 void (*f)(char*), gpointer userdata); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
107 void cmd_del (const char *name); |
1830 | 108 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
109 |
1830 | 110 These two functions are provided to declare mcabber commands, offered by |
111 your module. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
112 - name is a command name. |
1830 | 113 - help is a short description of your command, however for now it is |
114 not used at all and can be omitted. | |
115 - flags are completion identifiers for first and second command | |
116 arguments, for list of built-in completions, see compl.h. You can | |
117 declare your own completion lists, using functions from compl.h, | |
118 described later. | |
119 - f is a user-provided callback function, that will be called upon | |
120 executing mcabber command. If you will provide non-NULL userdata, | |
121 function must be of type | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
122 void (*f) (char *commandline, gpointer userdata). |
1830 | 123 - userdata is a pointer to data, transparently passed to callback. |
124 See f description. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
125 |
1830 | 126 ------------------------------------------------------------------------ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
127 #include <mcabber/compl.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
128 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
129 guint compl_new_category (void); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
130 void compl_del_category (guint id); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
131 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
132 void compl_add_category_word (guint categ, |
1830 | 133 const char *command); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
134 void compl_del_category_word (guint categ, |
1830 | 135 const char *word); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
136 GSList *compl_get_category_list (guint cat_flags, |
1830 | 137 guint *dynlist); |
138 ------------------------------------------------------------------------ | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
139 |
1830 | 140 These functions allow you to define and manage word lists for completion |
141 categories, used by your commands. First you need to obtain handle for | |
142 completion type, that you later will supply as flags, when declaring | |
143 your commands. For that use function compl_new_category. It returns | |
144 new category id, or zero if mcabber runs out of completion ids (for now | |
145 there are only 32 ids available, and 20 of them are already used for | |
146 builtin commands). compl_del_category allows you to delete user-defined | |
147 category, deleting all words in it too. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
148 |
1830 | 149 Now, that you have a completion category, you can at any time add or |
150 delete words from its completion list. To do that, use the functions | |
151 compl_add_category_word and compl_del_category_word. You can obtain | |
152 current contents of category by using gompl_get_category_list. If after | |
153 execution dynlist is TRUE, you should free obtained list of words (both, | |
154 words and list). | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
155 |
1830 | 156 ------------------------------------------------------------------------ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
157 #include <mcabber/hooks.h> |
1830 | 158 |
159 typedef struct { | |
160 const char *name; | |
161 const char *value; | |
162 } hk_arg_t; | |
163 | |
164 typedef guint (*hk_handler_t) (const gchar *hookname, | |
165 hk_arg_t *args, | |
166 gpointer userdata); | |
167 | |
168 guint hk_add_handler (hk_handler_t handler, | |
169 const gchar *hookname, | |
170 gint priority, | |
171 gpointer userdata); | |
172 void hk_del_handler (const gchar *hookname, | |
173 guint hid); | |
174 ------------------------------------------------------------------------ | |
175 | |
176 These functions allow your module to react to events, such as incoming | |
177 and outgoing messages, buddy status changes and server connection | |
178 establishment or breakup. The hookname string specifies the events the | |
179 handler wants to subscribe to. The available strings can be found in | |
180 hooks.h. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
181 |
1830 | 182 The hk_add_handler() function will return a handler id which you will |
183 use to remove the handler with hk_del_handler(). | |
184 Args argument is a list of hk_arg_t structures, terminated by structure, | |
185 whose name field is set to NULL. | |
186 | |
187 Your handler should return one of the values in the hk_handler_result | |
188 enum (see hooks.h), usually HOOK_HANDLER_RESULT_ALLOW_MORE_HANDLERS so | |
189 that other handlers can be triggers as well. | |
190 | |
191 A handler can determine which event has occured by checking the hookname | |
192 argument (a same hook handler can subscribe to several events by using | |
193 hk_add_handler() several times). | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
194 |
1830 | 195 Currently the following events exist: |
196 - hook-pre-message-in (HOOK_PRE_MESSAGE_IN) with parameters | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
197 * jid - sender of the incoming message |
1830 | 198 * resource - resource of the incoming message |
199 * message - message body, converted to locale charset | |
200 * groupchat - ("true" or "false") | |
1892
ea3f9b4f3558
Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1830
diff
changeset
|
201 * delayed - message timestamp (ISO-8601 string) or empty string if |
ea3f9b4f3558
Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1830
diff
changeset
|
202 the message wasn't delayed |
1913
3cabdacf58df
Add "error" field to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1906
diff
changeset
|
203 * error - "true" if this is an error message |
1830 | 204 - hook-post-message-in (HOOK_POST_MESSAGE_IN) with parameters |
205 * jid - sender of the incoming message | |
206 * resource - resource of the incoming message | |
207 * message - message body, converted to locale charset | |
208 * groupchat - ("true" or "false") | |
209 * attention - In a MUC message, true if you've been highlighted | |
210 In a regular message, true if the sender has requested your | |
211 attention (only implemented for MUC currently) | |
1892
ea3f9b4f3558
Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1830
diff
changeset
|
212 * delayed - message timestamp (ISO-8601 string) or empty string if |
ea3f9b4f3558
Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1830
diff
changeset
|
213 the message wasn't delayed |
1913
3cabdacf58df
Add "error" field to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents:
1906
diff
changeset
|
214 * error - "true" if this is an error message |
1624
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
215 - hook-message-out (HOOK_MESSAGE_OUT) with parameters |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
216 * jid - recipient of the outgoing message |
1830 | 217 * message - message body, converted to locale charset |
1624
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
218 - hook-status-change (HOOK_STATUS_CHANGE) with |
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
219 parameters |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
220 * jid - buddy, whose status has changed |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
221 * resource - resource, whose status has changed |
1830 | 222 * old_status - old status of the buddy, one-char string, |
223 representing mcabber status letter - one of 'ofdna?_'. | |
224 * new_status - new buddy status. Same as above. | |
225 * message - new status message. Old one should still be | |
226 available to module as the current buddy's message. | |
1624
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
227 - hook-my-status-change (HOOK_MY_STATUS_CHANGE) with |
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
228 parameters |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
229 * new_status - user's new status, see |
1830 | 230 hook-status-change. Old one should still be |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
231 available as the current status of the user. |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
232 * message - new status message |
1683
b09f82f61745
Split HOOK_INTERNAL
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1669
diff
changeset
|
233 - hook-post-connect (HOOK_POST_CONNECT) with no parameters |
1830 | 234 - hook-pre-disconnect (HOOK_PRE_DISCONNECT) with no parameters |
235 - hook-unread-list-change (HOOK_UNREAD_LIST_CHANGE) | |
236 * unread - number of buffers with the pending message flag (#) | |
237 * attention - number of non-MUC buffers with the attention sign (!) | |
238 * muc_unread - number of MUC buffers with the unread message flag | |
239 * muc_attention - number of MUC buffers with the attention sign | |
1906
5d37cee8c6c6
Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents:
1892
diff
changeset
|
240 - hook-subscription (HOOK_SUBSCRIPTION) |
5d37cee8c6c6
Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents:
1892
diff
changeset
|
241 * type - the type of the subscription message received. Can be one |
5d37cee8c6c6
Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents:
1892
diff
changeset
|
242 of subscribe, unsubscribe, subscribed, unsubscribed. |
5d37cee8c6c6
Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents:
1892
diff
changeset
|
243 * jid - sender of the incoming subscription message |
5d37cee8c6c6
Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents:
1892
diff
changeset
|
244 * message - optional message sent with the request |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
245 |
1830 | 246 |
247 ------------------------------------------------------------------------ | |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
248 #include <mcabber/xmpp_helper.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
249 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
250 void xmpp_add_feature (const char *xmlns); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
251 void xmpp_del_feature (const char *xmlns); |
1830 | 252 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
253 |
1830 | 254 These functions may be useful, if your module implements some additional |
255 functionality to mcabber, that should be advertised in a client's | |
256 discovery features list. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
257 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
258 ===================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
259 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
260 Example: hello |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
261 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
262 ===================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
263 |
1830 | 264 Now, let's write a simple module, called "hello", that will do no more |
265 than just print something on loading and unloading. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
266 |
1830 | 267 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
268 #include <glib.h> |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
269 #include <gmodule.h> |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
270 |
1830 | 271 /* We will use scr_log_print() mcabber function, |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
272 that does mcabber's messages output */ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
273 #include <mcabber/logprint.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
274 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
275 /* Print something on module loading */ |
1830 | 276 const gchar* g_module_check_init(GModule *module) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
277 { |
1830 | 278 scr_log_print(LPRINT_NORMAL, "Hello, World!"); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
279 return NULL; |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
280 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
281 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
282 /* ... and unloading */ |
1830 | 283 void g_module_unload(GModule *module) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
284 { |
1830 | 285 scr_log_print(LPRINT_NORMAL, "Bye, World!"); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
286 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
287 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
288 /* The End */ |
1830 | 289 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
290 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
291 Now, compile this file (hello.c) with |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
292 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
293 libtool --mode=compile gcc `pkg-config --cflags glib-2.0 \ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
294 gmodule-2.0 mcabber` -c hello.c |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
295 libtool --mode=link gcc -module -rpath /usr/lib/mcabber/ \ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
296 `pkg-config --libs glib-2.0 gmodule-2.0 mcabber` \ |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
297 -o libhello.la hello.lo |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
298 |
1830 | 299 (you should substitute /usr/lib/mcabber to the directory where |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
300 your modules are located) and then install obtained module with |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
301 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
302 libtool --mode=install install libhello.la \ |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
303 /usr/lib/mcabber/libhello.la |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
304 |
1830 | 305 Note that you most likely need not run suggested by libtool finish |
306 action, as we're working with module object, not system- wide library, | |
307 but maybe some systems require that. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
308 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
309 Now, set modules_dir mcabber variable to point to your modules |
1830 | 310 directory, and try to run /module -f load hello. If all goes well, |
311 you should see in status buffer message "Hello World!" (as well as | |
312 some complaints, as we forced module loading). | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
313 Now unload module by running command /module unload hello, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
314 that should bring up message "Bye, World!". |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
315 |
1830 | 316 That's it, you just created very simple dynamically loadable mcabber |
317 module. But, as you noticed, it needs force to be loaded. Now, let's | |
318 add the information structure that mcabber wants. | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
319 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
320 ========================== |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
321 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
322 Example: info struct |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
323 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
324 ========================== |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
325 |
1830 | 326 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
327 #include <mcabber/logprint.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
328 /* module_info_t definition */ |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
329 #include <mcabber/modules.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
330 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
331 /* Print something on module loading */ |
1830 | 332 void hello_init(void) |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
333 { |
1830 | 334 scr_log_print(LPRINT_NORMAL, "Hello, World!"); |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
335 } |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
336 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
337 /* ... and unloading */ |
1830 | 338 void hello_uninit(void) |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
339 { |
1830 | 340 scr_log_print(LPRINT_NORMAL, "Bye, World!"); |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
341 } |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
342 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
343 module_info_t info_hello = { |
1752 | 344 .branch = "dev", |
345 .api = 1, | |
1830 | 346 .version = "0.0.1", |
347 .description = "Hello world module\n" | |
348 " (as well as bye world module)", | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
349 .requires = NULL, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
350 .init = hello_init, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
351 .uninit = hello_uninit, |
1752 | 352 .next = NULL, |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
353 }; |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
354 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
355 /* The End */ |
1830 | 356 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
357 |
1830 | 358 Here we still do not use glib nor gmodule, so, we can omit them in |
359 compilation lines: | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
360 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
361 libtool --mode=compile gcc `pkg-config --cflags mcabber` \ |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
362 -c hello.c |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
363 libtool --mode=link gcc -module -rpath /usr/lib/mcabber/ \ |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
364 `pkg-config --libs mcabber` -o libhello.la hello.lo |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
365 |
1830 | 366 Again compile it, copy, and try to load, now without -f flag. As you |
367 may notice, when loading previous example, mcabber first printed "Hello, | |
368 World!", and only then complaint about module not having information | |
369 struct. That's because g_module_check_init is called right after module | |
370 loading, before mcabber even has a chance to look at module, while .init | |
371 from info struct is called afterwards by mcabber itself. You can try to | |
372 introduce some error (e.g. too high or missing target mcabber version) | |
373 and see the difference. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
374 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
375 ======================= |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
376 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
377 Example: command |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
378 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
379 ======================= |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
380 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
381 Now, let's allow our module to do some real work. |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
382 |
1830 | 383 ------------------------------------------------------------------------ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
384 #include <mcabber/logprint.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
385 #include <mcabber/commands.h> |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
386 #include <mcabber/modules.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
387 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
388 /* Handler for command */ |
1830 | 389 void do_hello(char *args) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
390 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
391 /* args contains command line with command |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
392 * name and any spaces after it stripped */ |
1830 | 393 scr_log_print(LPRINT_NORMAL, "Hello, %s!", |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
394 *args != '\0' ? args : "World"); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
395 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
396 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
397 /* Register command */ |
1830 | 398 void hello_init(void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
399 { |
1830 | 400 cmd_add("hello", "", 0, 0, do_hello, NULL); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
401 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
402 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
403 /* Unregister command */ |
1830 | 404 void hello_uninit(void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
405 { |
1830 | 406 cmd_del("hello"); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
407 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
408 |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
409 module_info_t hello_info = { |
1752 | 410 .branch = "dev", |
411 .api = 1, | |
1830 | 412 .version = "0.0.2", |
413 .description = "Hello world module\n" | |
414 " Provides command /hello", | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
415 .requires = NULL, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
416 .init = hello_init, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
417 .uninit = hello_uninit, |
1752 | 418 .next = NULL, |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
419 } |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
420 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
421 /* The End */ |
1830 | 422 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
423 |
1830 | 424 Now, compile it and try to load and run /hello with some arguments. |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
425 |
1830 | 426 Note, that we used one-argument version of command handler, as we have |
427 specified no userdata. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
428 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
429 ========================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
430 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
431 Example: completion |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
432 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
433 ========================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
434 |
1830 | 435 Now let's investigate how to provide custom completion to your commands. |
436 You can as well use built-in completions, their IDs are listed in | |
437 compl.h. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
438 |
1830 | 439 ------------------------------------------------------------------------ |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
440 #include <mcabber/logprint.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
441 #include <mcabber/commands.h> |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
442 #include <mcabber/modules.h> |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
443 #include <mcabber/compl.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
444 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
445 static guint hello_cid = 0; |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
446 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
447 /* hello command handler */ |
1830 | 448 void do_hello(char *args) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
449 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
450 /* If argument is provided, add it to |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
451 * completions list. */ |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
452 if (hello_cid && *args != '\0') |
1830 | 453 compl_add_category_word(hello_cid, |
454 args); | |
455 scr_log_print(LPRINT_NORMAL, "Hello, %s!", | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
456 *args != '\0' ? args : "World"); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
457 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
458 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
459 /* Initialization */ |
1830 | 460 void hello_init(void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
461 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
462 /* Obtain handle for our completion |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
463 * category */ |
1830 | 464 hello_cid = compl_new_category(); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
465 if (hello_cid) |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
466 /* Add known default word to |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
467 * completion list */ |
1830 | 468 compl_add_category_word(hello_cid, |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
469 "World"); |
1830 | 470 cmd_add("hello", "", hello_cid, 0, do_hello, |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
471 NULL); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
472 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
473 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
474 /* Deinitialization */ |
1830 | 475 void hello_uninit(void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
476 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
477 /* Give back category handle */ |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
478 if (hello_cid) |
1830 | 479 compl_del_category(hello_cid); |
480 cmd_del("hello"); | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
481 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
482 |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
483 module_info_t hello_info = { |
1752 | 484 .branch = "dev", |
485 .api = 1, | |
1830 | 486 .version = "0.0.3", |
487 .description = "Hello world module" | |
488 " Provides command /hello with completion", | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
489 .requires = NULL, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
490 .init = hello_init, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
491 .uninit = hello_uninit, |
1752 | 492 .next = NULL, |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
493 } |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
494 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
495 /* The End */ |
1830 | 496 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
497 |
1830 | 498 Now you can use completion for hello command. Note, that this code have |
499 some serious simplifications, made for simplicity reasons. For now, | |
500 compl_add_category_word does not checks, if word already exists in | |
501 completions list (although it is marked as TODO, so, some day it will), | |
502 so, we should check it ourselves. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
503 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
504 ===================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
505 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
506 Example: hooks |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
507 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
508 ===================== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
509 |
1830 | 510 Now let's implement our own beeper. Why may anyone wish to do this? |
511 I am not satisfied with default mcabber's builtin beeper flexibility. | |
512 I wanted beeping on any MUC conference message, not just the ones | |
513 directed to me. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
514 |
1830 | 515 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
516 #include <string.h> |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
517 |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
518 #include <mcabber/logprint.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
519 #include <mcabber/commands.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
520 #include <mcabber/compl.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
521 #include <mcabber/hooks.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
522 #include <mcabber/screen.h> |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
523 #include <mcabber/settings.h> |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
524 #include <mcabber/module.h> |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
525 |
1830 | 526 static guint beep_cid = 0; /* Command completion category id */ |
527 static guint beep_hid = 0; /* Hook handler id */ | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
528 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
529 /* Event handler */ |
1830 | 530 static guint beep_hh(const gchar *hookname, hk_arg_t *args, |
531 gpointer userdata) | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
532 { |
1624
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
533 /* Check if beeping is enabled */ |
1830 | 534 if (settings_opt_get_int("beep_enable")) |
535 scr_Beep(); /* *BEEP*! */ | |
536 | |
537 return HOOK_HANDLER_RESULT_ALLOW_MORE_HANDLERS; | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
538 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
539 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
540 /* beep command handler */ |
1830 | 541 static void do_beep(char *args) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
542 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
543 /* Check arguments, and if recognized, |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
544 * set mcabber option accordingly */ |
1830 | 545 if (!strcmp(args, "enable") || |
546 !strcmp(args, "on") || | |
547 !strcmp(args, "yes") || | |
548 !strcmp(args, "1")) | |
549 settings_set(SETTINGS_TYPE_OPTION, | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
550 "beep_enable", "1"); |
1830 | 551 else if (!strcmp(args, "disable") || |
552 !strcmp(args, "off") || | |
553 !strcmp(args, "no") || | |
554 !strcmp(args, "0")) | |
555 settings_set(SETTINGS_TYPE_OPTION, | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
556 "beep_enable", "0"); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
557 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
558 /* Output current state, either if state is |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
559 * changed and if argument is not recognized */ |
1830 | 560 if (settings_opt_get_int("beep_enable")) |
561 scr_log_print(LPRINT_NORMAL, | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
562 "Beep on messages is enabled"); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
563 else |
1830 | 564 scr_log_print(LPRINT_NORMAL, |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
565 "Beep on messages is disabled"); |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
566 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
567 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
568 /* Initialization */ |
1830 | 569 static void beep_init (void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
570 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
571 /* Create completions */ |
1830 | 572 beep_cid = compl_new_category(); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
573 if (beep_cid) { |
1830 | 574 compl_add_category_word(beep_cid, "enable"); |
575 compl_add_category_word(beep_cid, "disable"); | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
576 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
577 /* Add command */ |
1830 | 578 cmd_add("beep", "", beep_cid, 0, do_beep, NULL); |
1624
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
579 /* Add handler |
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
580 * We are only interested in incoming message events |
a75611931642
Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1619
diff
changeset
|
581 */ |
1830 | 582 beep_hid = hk_add_handler(beep_hh, HOOK_POST_MESSAGE_IN, |
583 G_PRIORITY_DEFAULT_IDLE, NULL); | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
584 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
585 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
586 /* Deinitialization */ |
1830 | 587 void beep_uninit(void) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
588 { |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
589 /* Unregister event handler */ |
1830 | 590 hk_del_handler(HOOK_POST_MESSAGE_IN, beep_hid); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
591 /* Unregister command */ |
1830 | 592 cmd_del("beep"); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
593 /* Give back completion handle */ |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
594 if (beep_cid) |
1830 | 595 compl_del_category(beep_cid); |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
596 } |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
597 |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
598 module_info_t beep_info = { |
1752 | 599 .branch = "dev", |
600 .api = 1, | |
1830 | 601 .version = "0.0.1", |
602 .description = "Simple beeper module\n" | |
603 " Recognizes option beep_enable\n" | |
604 " Provides command /beep", | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
605 .requires = NULL, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
606 .init = beep_init, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
607 .uninit = beep_uninit, |
1752 | 608 .next = NULL, |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
609 } |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
610 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
611 /* The End */ |
1830 | 612 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
613 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
614 If you use CMake (as do I), corresponding CMakeLists.txt |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
615 snippet: |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
616 |
1830 | 617 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
618 cmake_minimum_required(VERSION 2.6) |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
619 project(beep C) |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
620 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
621 find_package(PkgConfig REQUIRED) |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
622 pkg_check_modules(MCABBER REQUIRED mcabber) |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
623 # this one should be before any target definitions |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
624 link_directories(${MCABBER_LIBRARY_DIRS}) |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
625 |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
626 add_library(beep MODULE beep.c) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
627 |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
628 include_directories(SYSTEM ${MCABBER_INCLUDE_DIRS}) |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
629 target_link_libraries(beep ${MCABBER_LIBRARIES) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
630 include_directories(${beep_SOURCE_DIR} |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
631 ${beep_BINARY_DIR}) |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
632 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
633 install(TARGETS beep DESTINATION lib/mcabber) |
1830 | 634 ------------------------------------------------------------------------ |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
635 |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
636 =========================== |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
637 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
638 Example: dependencies |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
639 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
640 =========================== |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
641 |
1830 | 642 I will not provide here a complete example of two modules, one of which |
643 depends on other, only some use cases. | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
644 |
1830 | 645 Info struct for module, that depends on two other modules: |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
646 |
1830 | 647 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
648 #include <mcabber/modules.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
649 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
650 const gchar *a_deps[] = { "b", "c", NULL }; |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
651 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
652 module_info_t info_a = { |
1752 | 653 .branch = "dev", |
654 .api = 1, | |
1830 | 655 .version = NULL, |
656 .description = NULL, | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
657 .requires = a_deps, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
658 .init = a_init, |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
659 .uninit = a_uninit, |
1752 | 660 .next = NULL, |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
661 }; |
1830 | 662 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
663 |
1830 | 664 If your module needs to "authenticate" mcabber version too, this can be |
665 done in g_module_check_init: | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
666 |
1830 | 667 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
668 #include <glib.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
669 #include <gmodule.h> |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
670 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
671 #include <mcabber/main.h> |
1752 | 672 #include <mcabber/modules.h> |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
673 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
674 const gchar *g_module_check_init (GModule *module) |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
675 { |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
676 char *ver = mcabber_version (); |
1752 | 677 // ver now contains version in format |
678 // X.X.X[-xxx][ (XXXXXXXXXXXXX)] | |
679 const gchar *branch = mcabber_branch; | |
680 guint api = mcabber_api_version; | |
681 const gchar *error = NULL; | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
682 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
683 if (...) |
1752 | 684 error = "Incompatible mcabber version"; |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
685 |
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
686 g_free (ver); |
1752 | 687 return error; |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
688 } |
1830 | 689 ------------------------------------------------------------------------ |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
690 |
1830 | 691 Also you can use glib check_init routine to modify module information, |
692 that will be checked by mcabber, e.g. if you want your module to always | |
693 pass mcabber version check, you can assign branch information, obtained | |
694 from mcabber_... variables to corresponding fields in your struct. | |
695 Or you can modify your module's dependencies, though direct | |
696 module_load() will have the same effect, and can be used for optional | |
697 dependencies, that your module can still work without. | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
698 |
1830 | 699 Note: remember, that g_module_check_init will be always called, even if |
700 later the module will not pass checks, thus: | |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
701 - do not use functions from other modules there; |
1830 | 702 - provide g_module_unload to undo anything, check_init has done. |
1735
5093b5ca1572
New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1683
diff
changeset
|
703 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
704 ============== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
705 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
706 Further |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
707 |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
708 ============== |
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
709 |
1830 | 710 As mcabber now uses glib mainloop, you can use glib's event sources, for |
711 example, fifo reading already uses GIOChannels for non-blocking IO. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
712 |
1830 | 713 You can extend XMPP part of mcabber functionality by providing lm |
714 message handlers with high priority and allowing unhandled by your | |
715 handler messages be taken care by mcabber's handlers on normal priority | |
716 level. This is where you may need to modify set of advertised supported | |
717 disco features. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
718 |
1830 | 719 Many useful examples can be found in my modules, that can be found at |
720 http://isbear.unixzone.org.ua/source. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
721 |
1830 | 722 If you think, that your module needs to change something, hardcoded in |
723 current implementation - feel free to mail me or join mcabber's MUC room | |
724 and discuss it - for now we have only implemented things, that we have | |
725 found necessary for our own modules. | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
726 |
1830 | 727 Also I am not native English speaker, so, if you find some errors or |
728 non-natural constructs in this howto, please, inform me (I will be glad, | |
729 if you also provide a more suitable version of text in question). | |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
730 |
1669
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
731 -- Myhailo Danylenko |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
732 -- mailto:isbear@ukrpost.net |
004739237999
Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
1625
diff
changeset
|
733 -- xmpp:isbear@unixzone.org.ua |
1830 | 734 -- Sat, 27 Mar 2010 13:30:00 +0100 |
1619
2a82e6654c04
Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff
changeset
|
735 |