mcabber: mcabber/doc/HOWTO_modules.txt annotate

annotate mcabber/doc/HOWTO_modules.txt @ 1754:d8442bcb33b7

Reorder fields in module info struct

author	Myhailo Danylenko <isbear@ukrpost.net>
date	Sat, 13 Mar 2010 12:30:30 +0200
parents	4a7c7900f600
children	7befbd8e932d

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

Mercurial > ~mikael > mcabber > hg

annotate mcabber/doc/HOWTO_modules.txt @ 1754:d8442bcb33b7