annotate mcabber/doc/HOWTO_modules.txt @ 2141:e702073612de

Add "hook-mdr-received" hook This hook is triggered when a XEP-0184 Message Delivery Report is received.
author Mikael Berthe <mikael@lilotux.net>
date Sun, 06 Jul 2014 14:48:59 +0200
parents 3cabdacf58df
children a54c084af4d6
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
1913
3cabdacf58df Add "error" field to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents: 1906
diff changeset
203 * error - "true" if this is an error message
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
204 - hook-post-message-in (HOOK_POST_MESSAGE_IN) with parameters
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
205 * jid - sender of the incoming message
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
206 * resource - resource of the incoming message
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
207 * message - message body, converted to locale charset
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
208 * groupchat - ("true" or "false")
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
209 * attention - In a MUC message, true if you've been highlighted
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
210 In a regular message, true if the sender has requested your
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
211 attention (only implemented for MUC currently)
1892
ea3f9b4f3558 Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents: 1830
diff changeset
212 * delayed - message timestamp (ISO-8601 string) or empty string if
ea3f9b4f3558 Add "delayed" argument to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents: 1830
diff changeset
213 the message wasn't delayed
1913
3cabdacf58df Add "error" field to the message-in hooks
Mikael Berthe <mikael@lilotux.net>
parents: 1906
diff changeset
214 * error - "true" if this is an error message
1624
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
215 - hook-message-out (HOOK_MESSAGE_OUT) with parameters
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
216 * jid - recipient of the outgoing message
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
217 * message - message body, converted to locale charset
2141
e702073612de Add "hook-mdr-received" hook
Mikael Berthe <mikael@lilotux.net>
parents: 1913
diff changeset
218 - hook-mdr-received (HOOK_MDR_RECEIVED) with parameter
e702073612de Add "hook-mdr-received" hook
Mikael Berthe <mikael@lilotux.net>
parents: 1913
diff changeset
219 * jid - recipient of the outgoing message
1624
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
220 - hook-status-change (HOOK_STATUS_CHANGE) with
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
221 parameters
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
222 * jid - buddy, whose status has changed
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
223 * resource - resource, whose status has changed
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
224 * old_status - old status of the buddy, one-char string,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
225 representing mcabber status letter - one of 'ofdna?_'.
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
226 * new_status - new buddy status. Same as above.
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
227 * message - new status message. Old one should still be
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
228 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
229 - 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
230 parameters
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
231 * new_status - user's new status, see
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
232 hook-status-change. Old one should still be
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
233 available as the current status of the user.
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
234 * message - new status message
1683
b09f82f61745 Split HOOK_INTERNAL
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1669
diff changeset
235 - hook-post-connect (HOOK_POST_CONNECT) with no parameters
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
236 - hook-pre-disconnect (HOOK_PRE_DISCONNECT) with no parameters
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
237 - hook-unread-list-change (HOOK_UNREAD_LIST_CHANGE)
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
238 * unread - number of buffers with the pending message flag (#)
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
239 * attention - number of non-MUC buffers with the attention sign (!)
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
240 * muc_unread - number of MUC buffers with the unread message flag
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
241 * muc_attention - number of MUC buffers with the attention sign
1906
5d37cee8c6c6 Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents: 1892
diff changeset
242 - hook-subscription (HOOK_SUBSCRIPTION)
5d37cee8c6c6 Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents: 1892
diff changeset
243 * type - the type of the subscription message received. Can be one
5d37cee8c6c6 Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents: 1892
diff changeset
244 of subscribe, unsubscribe, subscribed, unsubscribed.
5d37cee8c6c6 Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents: 1892
diff changeset
245 * jid - sender of the incoming subscription message
5d37cee8c6c6 Add "hook-subscription" hook and hk_subscription()
Mikael Berthe <mikael@lilotux.net>
parents: 1892
diff changeset
246 * message - optional message sent with the request
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
247
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
248
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
249 ------------------------------------------------------------------------
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
250 #include <mcabber/xmpp_helper.h>
1619
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 void xmpp_add_feature (const char *xmlns);
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
253 void xmpp_del_feature (const char *xmlns);
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
254 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
255
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
256 These functions may be useful, if your module implements some additional
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
257 functionality to mcabber, that should be advertised in a client's
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
258 discovery features list.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
259
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
260 =====================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
261
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
262 Example: hello
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
263
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
264 =====================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
265
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
266 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
267 than just print something on loading and unloading.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
268
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
269 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
270 #include <glib.h>
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
271 #include <gmodule.h>
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
272
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
273 /* We will use scr_log_print() mcabber function,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
274 that does mcabber's messages output */
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
275 #include <mcabber/logprint.h>
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
276
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
277 /* Print something on module loading */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
278 const gchar* g_module_check_init(GModule *module)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
279 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
280 scr_log_print(LPRINT_NORMAL, "Hello, World!");
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
281 return NULL;
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
282 }
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 /* ... and unloading */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
285 void g_module_unload(GModule *module)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
286 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
287 scr_log_print(LPRINT_NORMAL, "Bye, World!");
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
288 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
289
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
290 /* The End */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
291 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
292
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
293 Now, compile this file (hello.c) 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=compile gcc `pkg-config --cflags glib-2.0 \
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
296 gmodule-2.0 mcabber` -c hello.c
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
297 libtool --mode=link gcc -module -rpath /usr/lib/mcabber/ \
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
298 `pkg-config --libs glib-2.0 gmodule-2.0 mcabber` \
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
299 -o libhello.la hello.lo
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
300
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
301 (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
302 your modules are located) and then install obtained module with
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
303
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
304 libtool --mode=install install libhello.la \
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
305 /usr/lib/mcabber/libhello.la
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
306
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
307 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
308 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
309 but maybe some systems require that.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
310
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
311 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
312 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
313 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
314 some complaints, as we forced module loading).
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
315 Now unload module by running command /module unload hello,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
316 that should bring up message "Bye, World!".
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
317
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
318 That's it, you just created very simple dynamically loadable mcabber
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
319 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
320 add the information structure that mcabber wants.
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
321
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
322 ==========================
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 Example: info struct
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
325
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
326 ==========================
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
327
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
328 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
329 #include <mcabber/logprint.h>
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
330 /* module_info_t definition */
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
331 #include <mcabber/modules.h>
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
332
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
333 /* Print something on module loading */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
334 void hello_init(void)
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
335 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
336 scr_log_print(LPRINT_NORMAL, "Hello, World!");
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
337 }
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
338
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
339 /* ... and unloading */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
340 void hello_uninit(void)
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
341 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
342 scr_log_print(LPRINT_NORMAL, "Bye, World!");
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
343 }
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
344
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
345 module_info_t info_hello = {
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
346 .branch = "dev",
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
347 .api = 1,
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
348 .version = "0.0.1",
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
349 .description = "Hello world module\n"
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
350 " (as well as bye world module)",
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
351 .requires = NULL,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
352 .init = hello_init,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
353 .uninit = hello_uninit,
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
354 .next = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
355 };
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
356
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
357 /* The End */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
358 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
359
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
360 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
361 compilation lines:
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
362
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
363 libtool --mode=compile gcc `pkg-config --cflags mcabber` \
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
364 -c hello.c
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
365 libtool --mode=link gcc -module -rpath /usr/lib/mcabber/ \
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
366 `pkg-config --libs mcabber` -o libhello.la hello.lo
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
367
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
368 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
369 may notice, when loading previous example, mcabber first printed "Hello,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
370 World!", and only then complaint about module not having information
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
371 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
372 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
373 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
374 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
375 and see the difference.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
376
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
377 =======================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
378
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
379 Example: command
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 =======================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
382
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
383 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
384
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
385 ------------------------------------------------------------------------
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
386 #include <mcabber/logprint.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
387 #include <mcabber/commands.h>
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
388 #include <mcabber/modules.h>
1619
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 /* Handler for command */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
391 void do_hello(char *args)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
392 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
393 /* args contains command line with command
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
394 * name and any spaces after it stripped */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
395 scr_log_print(LPRINT_NORMAL, "Hello, %s!",
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
396 *args != '\0' ? args : "World");
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
397 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
398
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
399 /* Register command */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
400 void hello_init(void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
401 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
402 cmd_add("hello", "", 0, 0, do_hello, NULL);
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
403 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
404
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
405 /* Unregister command */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
406 void hello_uninit(void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
407 {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
408 cmd_del("hello");
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
409 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
410
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
411 module_info_t hello_info = {
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
412 .branch = "dev",
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
413 .api = 1,
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
414 .version = "0.0.2",
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
415 .description = "Hello world module\n"
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
416 " Provides command /hello",
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
417 .requires = NULL,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
418 .init = hello_init,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
419 .uninit = hello_uninit,
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
420 .next = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
421 }
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
422
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
423 /* The End */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
424 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
425
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
426 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
427
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
428 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
429 specified no userdata.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
430
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
431 ==========================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
432
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
433 Example: completion
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
434
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
435 ==========================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
436
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
437 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
438 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
439 compl.h.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
440
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
441 ------------------------------------------------------------------------
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
442 #include <mcabber/logprint.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
443 #include <mcabber/commands.h>
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
444 #include <mcabber/modules.h>
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
445 #include <mcabber/compl.h>
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
446
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
447 static guint hello_cid = 0;
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
448
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
449 /* hello command handler */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
450 void do_hello(char *args)
1619
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 /* If argument is provided, add it to
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
453 * completions list. */
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
454 if (hello_cid && *args != '\0')
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
455 compl_add_category_word(hello_cid,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
456 args);
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
457 scr_log_print(LPRINT_NORMAL, "Hello, %s!",
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
458 *args != '\0' ? args : "World");
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
459 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
460
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
461 /* Initialization */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
462 void hello_init(void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
463 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
464 /* Obtain handle for our completion
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
465 * category */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
466 hello_cid = compl_new_category();
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
467 if (hello_cid)
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
468 /* Add known default word to
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
469 * completion list */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
470 compl_add_category_word(hello_cid,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
471 "World");
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
472 cmd_add("hello", "", hello_cid, 0, do_hello,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
473 NULL);
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
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
476 /* Deinitialization */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
477 void hello_uninit(void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
478 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
479 /* Give back category handle */
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
480 if (hello_cid)
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
481 compl_del_category(hello_cid);
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
482 cmd_del("hello");
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
483 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
484
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
485 module_info_t hello_info = {
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
486 .branch = "dev",
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
487 .api = 1,
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
488 .version = "0.0.3",
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
489 .description = "Hello world module"
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
490 " Provides command /hello with completion",
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
491 .requires = NULL,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
492 .init = hello_init,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
493 .uninit = hello_uninit,
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
494 .next = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
495 }
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
496
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
497 /* The End */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
498 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
499
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
500 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
501 some serious simplifications, made for simplicity reasons. For now,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
502 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
503 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
504 so, we should check it ourselves.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
505
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
506 =====================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
507
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
508 Example: hooks
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
509
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
510 =====================
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
511
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
512 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
513 I am not satisfied with default mcabber's builtin beeper flexibility.
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
514 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
515 directed to me.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
516
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
517 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
518 #include <string.h>
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
519
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
520 #include <mcabber/logprint.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
521 #include <mcabber/commands.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
522 #include <mcabber/compl.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
523 #include <mcabber/hooks.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
524 #include <mcabber/screen.h>
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
525 #include <mcabber/settings.h>
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
526 #include <mcabber/module.h>
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
527
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
528 static guint beep_cid = 0; /* Command completion category id */
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
529 static guint beep_hid = 0; /* Hook handler id */
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
530
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
531 /* Event handler */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
532 static guint beep_hh(const gchar *hookname, hk_arg_t *args,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
533 gpointer userdata)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
534 {
1624
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
535 /* Check if beeping is enabled */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
536 if (settings_opt_get_int("beep_enable"))
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
537 scr_Beep(); /* *BEEP*! */
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
538
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
539 return HOOK_HANDLER_RESULT_ALLOW_MORE_HANDLERS;
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
540 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
541
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
542 /* beep command handler */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
543 static void do_beep(char *args)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
544 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
545 /* Check arguments, and if recognized,
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
546 * set mcabber option accordingly */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
547 if (!strcmp(args, "enable") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
548 !strcmp(args, "on") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
549 !strcmp(args, "yes") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
550 !strcmp(args, "1"))
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
551 settings_set(SETTINGS_TYPE_OPTION,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
552 "beep_enable", "1");
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
553 else if (!strcmp(args, "disable") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
554 !strcmp(args, "off") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
555 !strcmp(args, "no") ||
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
556 !strcmp(args, "0"))
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
557 settings_set(SETTINGS_TYPE_OPTION,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
558 "beep_enable", "0");
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 /* Output current state, either if state is
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
561 * changed and if argument is not recognized */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
562 if (settings_opt_get_int("beep_enable"))
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
563 scr_log_print(LPRINT_NORMAL,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
564 "Beep on messages is enabled");
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
565 else
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
566 scr_log_print(LPRINT_NORMAL,
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
567 "Beep on messages is disabled");
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
568 }
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 /* Initialization */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
571 static void beep_init (void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
572 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
573 /* Create completions */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
574 beep_cid = compl_new_category();
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
575 if (beep_cid) {
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
576 compl_add_category_word(beep_cid, "enable");
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
577 compl_add_category_word(beep_cid, "disable");
1619
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 /* Add command */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
580 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
581 /* Add handler
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
582 * We are only interested in incoming message events
a75611931642 Hook handler flags updates to howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1619
diff changeset
583 */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
584 beep_hid = hk_add_handler(beep_hh, HOOK_POST_MESSAGE_IN,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
585 G_PRIORITY_DEFAULT_IDLE, NULL);
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
586 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
587
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
588 /* Deinitialization */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
589 void beep_uninit(void)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
590 {
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
591 /* Unregister event handler */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
592 hk_del_handler(HOOK_POST_MESSAGE_IN, beep_hid);
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
593 /* Unregister command */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
594 cmd_del("beep");
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
595 /* Give back completion handle */
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
596 if (beep_cid)
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
597 compl_del_category(beep_cid);
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
598 }
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
599
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
600 module_info_t beep_info = {
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
601 .branch = "dev",
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
602 .api = 1,
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
603 .version = "0.0.1",
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
604 .description = "Simple beeper module\n"
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
605 " Recognizes option beep_enable\n"
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
606 " Provides command /beep",
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
607 .requires = NULL,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
608 .init = beep_init,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
609 .uninit = beep_uninit,
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
610 .next = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
611 }
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
612
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
613 /* The End */
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
614 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
615
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
616 If you use CMake (as do I), corresponding CMakeLists.txt
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
617 snippet:
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
618
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
619 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
620 cmake_minimum_required(VERSION 2.6)
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
621 project(beep C)
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
622
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
623 find_package(PkgConfig REQUIRED)
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
624 pkg_check_modules(MCABBER REQUIRED mcabber)
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
625 # this one should be before any target definitions
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
626 link_directories(${MCABBER_LIBRARY_DIRS})
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
627
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
628 add_library(beep MODULE beep.c)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
629
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
630 include_directories(SYSTEM ${MCABBER_INCLUDE_DIRS})
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
631 target_link_libraries(beep ${MCABBER_LIBRARIES)
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
632 include_directories(${beep_SOURCE_DIR}
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
633 ${beep_BINARY_DIR})
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
634
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
635 install(TARGETS beep DESTINATION lib/mcabber)
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
636 ------------------------------------------------------------------------
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
637
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
638 ===========================
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
639
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
640 Example: dependencies
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
641
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
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
644 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
645 depends on other, only some use cases.
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
646
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
647 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
648
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
649 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
650 #include <mcabber/modules.h>
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
651
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
652 const gchar *a_deps[] = { "b", "c", NULL };
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
653
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
654 module_info_t info_a = {
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
655 .branch = "dev",
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
656 .api = 1,
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
657 .version = NULL,
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
658 .description = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
659 .requires = a_deps,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
660 .init = a_init,
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
661 .uninit = a_uninit,
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
662 .next = NULL,
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
663 };
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
664 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
665
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
666 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
667 done in g_module_check_init:
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
668
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
669 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
670 #include <glib.h>
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
671 #include <gmodule.h>
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
672
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
673 #include <mcabber/main.h>
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
674 #include <mcabber/modules.h>
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 const gchar *g_module_check_init (GModule *module)
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
677 {
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
678 char *ver = mcabber_version ();
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
679 // ver now contains version in format
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
680 // X.X.X[-xxx][ (XXXXXXXXXXXXX)]
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
681 const gchar *branch = mcabber_branch;
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
682 guint api = mcabber_api_version;
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
683 const gchar *error = NULL;
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
684
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
685 if (...)
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
686 error = "Incompatible mcabber version";
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
687
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
688 g_free (ver);
1752
4a7c7900f600 Update HOWTO
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1735
diff changeset
689 return error;
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
690 }
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
691 ------------------------------------------------------------------------
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
692
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
693 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
694 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
695 pass mcabber version check, you can assign branch information, obtained
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
696 from mcabber_... variables to corresponding fields in your struct.
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
697 Or you can modify your module's dependencies, though direct
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
698 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
699 dependencies, that your module can still work without.
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
700
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
701 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
702 later the module will not pass checks, thus:
1735
5093b5ca1572 New modules loading scheme
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1683
diff changeset
703 - do not use functions from other modules there;
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
704 - 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
705
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
706 ==============
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
707
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
708 Further
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
709
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
710 ==============
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 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
713 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
714
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
715 You can extend XMPP part of mcabber functionality by providing lm
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
716 message handlers with high priority and allowing unhandled by your
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
717 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
718 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
719 disco features.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
720
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
721 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
722 http://isbear.unixzone.org.ua/source.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
723
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
724 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
725 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
726 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
727 found necessary for our own modules.
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
728
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
729 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
730 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
731 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
732
1669
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
733 -- Myhailo Danylenko
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
734 -- mailto:isbear@ukrpost.net
004739237999 Update modules howto
Myhailo Danylenko <isbear@ukrpost.net>
parents: 1625
diff changeset
735 -- xmpp:isbear@unixzone.org.ua
1830
7befbd8e932d Update module howto
Mikael Berthe <mikael@lilotux.net>
parents: 1754
diff changeset
736 -- Sat, 27 Mar 2010 13:30:00 +0100
1619
2a82e6654c04 Add a module writing howto
Myhailo Danylenko <isbear@ukrpost.net>
parents:
diff changeset
737