New API call isoburn_is_compatible()

libisoburn/trunk/libisoburn/burn_wrap.c

@@ -59,6 +59,8 @@ int isoburn_initialize(char msg[1024], int flag)
  iso_lib_version(&major, &minor, &micro);
  sprintf(msg+strlen(msg), "libisofs-%d.%d.%d , ", major, minor, micro);
 
+ /* >>> check for suitability of library */
+
  if(!burn_initialize()) {
    sprintf(msg+strlen(msg), "Cannot initialize libburn\n");
    return(0);
@@ -66,6 +68,8 @@ int isoburn_initialize(char msg[1024], int flag)
  burn_version(&major, &minor, &micro);
  sprintf(msg+strlen(msg), "libburn-%d.%d.%d , ", major, minor, micro);
 
+ /* >>> check for suitability of library */
+
  isoburn_destroy_all(&isoburn_list_start, 0); /* isoburn_list_start= NULL */
  
  isoburn_version(&major, &minor, &micro);

libisoburn/trunk/libisoburn/isoburn.c

@@ -37,8 +37,10 @@
 
 #include "isoburn.h"
 
+/* No more: version numbers out of configure.ac
+   major.minor.micro now comes from libisoburn.h
 #include "../version.h"
-
+*/
 
 /* --------------------------  isoburn  ----------------------- */
 
@@ -408,9 +410,17 @@ int isoburn_prepare_new_image(struct burn_drive *d, struct burn_disc **disc,
 
 void isoburn_version(int *major, int *minor, int *micro)
 {
+ *major= isoburn_header_version_major;
+ *minor= isoburn_header_version_minor;
+ *micro= isoburn_header_version_micro;
+
+/* No more: values from version.h generated from version.h.in and
+            macro values defined in configure.ac
+
  *major = ISOBURN_MAJOR_VERSION;
  *minor = ISOBURN_MINOR_VERSION;
  *micro = ISOBURN_MICRO_VERSION;
+*/
 }
 
 

libisoburn/trunk/libisoburn/libisoburn.h

@@ -116,24 +116,65 @@ eventual multi-session emulation.
 int isoburn_initialize(char msg[1024], int flag);
 
 
-/** Obtain the three release version numbers of the library.
+/** Check whether all features of header file libisoburn.h from the given
+    major.minor.micro revision triple can be delivered by the library version
+    which is performing this call.
+    An application of libisoburn can easily memorize the version of the
+    libisofs.h header in its own code. Immediately after isoburn_initialize()
+    it should simply do this check:
+        if (! isoburn_is_compatible(isoburn_header_version_major,
+                                    isoburn_header_version_minor,
+                                    isoburn_header_version_micro, 0))
+           ...refuse to start the program with this dynamic library version...
+    @param major obtained at build time
+    @param minor obtained at build time
+    @param micro obtained at build time
+    @param flag Bitfield for control purposes. Unused yet. Submit 0.
+    @return 1= library can work for caller
+            0= library is not usable in some aspects. Caller must restrict
+               itself to an earlier API version or must not use this libray
+               at all.
+*/
+int isoburn_is_compatible(int major, int minor, int micro, int flag);
+
+
+/** These three release version numbers tell the revision of this header file
+    and of the API it describes. They are memorized by applications at build
+    time.
+*/
+#define isoburn_header_version_major  0
+#define isoburn_header_version_minor  0
+#define isoburn_header_version_micro  1
+/** Note:
+    Above version numbers are also recorded in configure.ac because libtool
+    wants them as parameters at build time.
+    For the library compatibility check ISOBURN_*_VERSION in configure.ac
+    are not decisive. Only the three numbers above do matter.
+*/
+
+
+/** Obtain the three release version numbers of the library. These are the
+    numbers encountered by the application when linking with lisbisoburn,
+    i.e. possibly not before run time.
+    Better do not base the fundamental compatibility decision of an application
+    on these numbers. For a reliable check use isoburn_is_compatible().
     @param major The maturity version (0 for now, as we are still learning)
     @param minor The development goal version.
     @param micro The development step version. This has an additional meaning:
+
                  Pare numbers indicate a version with frozen API. I.e. you can
                  rely on the same set of features to be present in all
                  published releases with that major.minor.micro combination.
                  Odd numbers indicate that API upgrades are in progress.
                  I.e. new features might be already present or they might
-                 be still missing. You need to check before compiling an
-                 application which relies on freshly introduced features.
+                 be still missing.
+                 So micro revisions {1,3,5,7,9} should never be used for
+                 dynamic linking unless the proper library match can be
+                 guaranteed by external circumstances.
 */
 void isoburn_version(int *major, int *minor, int *micro);
 
 
-/* >>> isoburn_is_compatible() */
-
-
 /** Aquire a target drive by its filesystem path resp. libburn persistent
     address.
     Wrapper for: burn_drive_scan_and_grab()
@@ -411,7 +452,7 @@ int isoburn_igopt_get_over_ugid(struct isoburn_imgen_opts *o,
                                int *replace_uid, int *replace_gid,
                                uid_t *uid, gid_t *gid);
 
-/** Set this to NULL to use the default charset.
+/** Set this to NULL to use the default output charset.
     >>> What if not NULL or not want default ?
 */
 int isoburn_igopt_set_out_charset(struct isoburn_imgen_opts *o,