# HG changeset patch
# User Myhailo Danylenko <isbear@ukrpost.net>
# Date 1268476515 -7200
# Node ID 4a7c7900f600d8ad0afc2172c1f57eda3e15c6b3
# Parent  c25f95b98377f5bc12792b7daac350c1b74ffb96
Update HOWTO

diff -r c25f95b98377 -r 4a7c7900f600 mcabber/doc/HOWTO_modules.txt
--- a/mcabber/doc/HOWTO_modules.txt	Sat Mar 13 10:47:14 2010 +0100
+++ b/mcabber/doc/HOWTO_modules.txt	Sat Mar 13 12:35:15 2010 +0200
@@ -17,20 +17,30 @@
   typedef void (*module_init_t)(void);
   typedef void (*module_uninit_t)(void);
 
-  typedef struct {
-    const gchar      *mcabber_version;
+  typedef struct module_info_struct module_info_t;
+  struct module_info_struct {
+    const gchar      *branch;
     module_init_t     init;
     module_uninit_t   uninit;
     const gchar     **requires;
-  } module_info_t;
+    guint             api;
+    const gchar      *version;
+    const gchar      *description;
+    module_info_t    *next;
+  };
 --------------------------------------------------------
 
 Callbacks init and uninit will be called after module
-and it's dependencies loading. 'requires' should contain
+and it's dependencies loading. 'requires' can contain a
 NULL-terminated list of module names, that should be loaded
-before this. 'mcabber_version' is required and should contain
-mcabber version, that this module is designed to work with.
-Three other fields may be NULL.
+before this. 'branch' and 'api' are required and should
+contain mcabber branch and api version, that this module is
+designed to work with. For these values see ChangeLog.api.
+'version' and 'description' fields are optional and just
+provide user with additional information about module.
+'description' field can contain newlines. 'next' field can
+contain pointer to the next struct with another branch of
+mcabber, if your module can work with multiple branches.
 
 To load modules, mcabber uses glib's GModule, thus, in your
 module you can also use functions
@@ -76,7 +86,8 @@
  - load .so via glib (and call g_module_check_init, if
    present)
  - check for information structure presence
- - check target mcabber version compatibility
+ - find suitable branch and check api version
+   compatibility
  - load modules, that this module requires (note, that
    dependency problems will be reported as error
    invariably, force flag have no effect on this check)
@@ -321,10 +332,15 @@
 }
 
 module_info_t info_hello = {
-	.mcabber_version = "0.10.0",
+	.branch          = "dev",
+	.api             = 1,
 	.requires        = NULL,
 	.init            = hello_init,
 	.uninit          = hello_uninit,
+	.version         = "0.0.1",
+	.description     = "Hello world module\n"
+		"(as well as bye world module)",
+	.next            = NULL,
 };
 
 /* The End */
@@ -384,10 +400,15 @@
 }
 
 module_info_t hello_info = {
-	.mcabber_version = "0.10.0",
+	.branch          = "dev",
+	.api             = 1,
 	.requires        = NULL,
 	.init            = hello_init,
 	.uninit          = hello_uninit,
+	.version         = "0.0.2",
+	.description     = "Hello world module\n"
+		"Provides command /hello",
+	.next            = NULL,
 }
 
 /* The End */
@@ -454,10 +475,15 @@
 }
 
 module_info_t hello_info = {
-	.mcabber_version = "0.10.0",
+	.branch          = "dev",
+	.api             = 1,
 	.requires        = NULL,
 	.init            = hello_init,
 	.uninit          = hello_uninit,
+	.version         = "0.0.3",
+	.description     = "Hello world module"
+		"Provides command /hello with completion",
+	.next            = NULL,
 }
 
 /* The End */
@@ -561,10 +587,16 @@
 }
 
 module_info_t beep_info = {
-	.mcabber_version = "0.10.0",
+	.branch          = "dev",
+	.api             = 1,
 	.requires        = NULL,
 	.init            = beep_init,
 	.uninit          = beep_uninit,
+	.version         = "0.0.1",
+	.description     = "Simple beeper module\n"
+		"Recognizes option beep_enable\n"
+		"Provides command /beep",
+	.next            = NULL,
 }
 
 /* The End */
@@ -611,10 +643,14 @@
 const gchar *a_deps[] = { "b", "c", NULL };
 
 module_info_t info_a = {
-	.mcabber_version = "0.10.0",
+	.branch          = "dev",
+	.api             = 1,
 	.requires        = a_deps,
 	.init            = a_init,
 	.uninit          = a_uninit,
+	.version         = NULL,
+	.description     = NULL,
+	.next            = NULL,
 };
 --------------------------------------------------------
 
@@ -626,30 +662,35 @@
 #include <gmodule.h>
 
 #include <mcabber/main.h>
+#include <mcabber/modules.h>
 
 const gchar *g_module_check_init (GModule *module)
 {
 	char *ver = mcabber_version ();
+	// ver now contains version in format
+	// X.X.X[-xxx][ (XXXXXXXXXXXXX)]
+	const gchar *branch = mcabber_branch;
+	guint api = mcabber_api_version;
+	const gchar *error = NULL;
 
-	// ver now contains version in format
-	// X.X.X[-xxx][ (XXXXXXXXX)]
 	if (...)
-		return "Incompatible mcabber version";
+		error = "Incompatible mcabber version";
 
 	g_free (ver);
-	return NULL;
+	return error;
 }
 --------------------------------------------------------
 
 Also you can use glib check_init routine to modify
 module information, that will be checked by mcabber,
 eg. if you want your module to always pass mcabber
-version check, you can assign version, obtained from
-mcabber_version() to corresponding field in your struct.
+version check, you can assign branch information,
+obtained from mcabber_... variables to corresponding
+fields in your struct.
 Or you can modify your module's dependencies, though
 direct module_load() will have the same effect, and
 can be used for optional dependencies, that your module
-can work without.
+can still work without.
 
 Note: remember, that g_module_check_init will be always
 called, even if later module will not pass checks, thus:
@@ -691,5 +732,5 @@
   -- Myhailo Danylenko
   -- mailto:isbear@ukrpost.net
   -- xmpp:isbear@unixzone.org.ua
-  -- Thu, 04 Mar 2010 09:32:38 +0200
+  -- Sat, 13 Mar 2010 12:18:17 +0200