annotate mcabber/doc/HOWTO_modules.txt @ 1892:ea3f9b4f3558

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