From ae30adf6e8d4c80e55aba74ed436870699e82118 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sat, 15 Sep 2007 17:16:49 +0000 Subject: [PATCH] Prepared for neat sed translation. Explained concept of libdax_msgs variants. --- libburn/trunk/cdrskin/cdrskin_timestamp.h | 2 +- libburn/trunk/libburn/libdax_msgs.h | 39 +++++++++++++++++++---- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/libburn/trunk/cdrskin/cdrskin_timestamp.h b/libburn/trunk/cdrskin/cdrskin_timestamp.h index f49497a6..10d89eb8 100644 --- a/libburn/trunk/cdrskin/cdrskin_timestamp.h +++ b/libburn/trunk/cdrskin/cdrskin_timestamp.h @@ -1 +1 @@ -#define Cdrskin_timestamP "2007.09.15.112311" +#define Cdrskin_timestamP "2007.09.15.171844" diff --git a/libburn/trunk/libburn/libdax_msgs.h b/libburn/trunk/libburn/libdax_msgs.h index 1e63a01c..1021c262 100644 --- a/libburn/trunk/libburn/libdax_msgs.h +++ b/libburn/trunk/libburn/libdax_msgs.h @@ -68,6 +68,31 @@ struct libdax_msgs { #ifndef LIBDAX_MSGS_H_INTERNAL + /* Architectural aspects */ +/* + libdax_msgs is designed to serve in libraries which want to offer their + applications a way to control the output of library messages. It shall be + incorporated by an owner, i.e. a software entity which encloses the code + of the .c file. + + Owner of libdax_msgs is libburn. A fully compatible variant named libiso_msgs + is owned by libisofs and can get generated by a script of the libburn + project: libburn/libdax_msgs_to_xyz_msgs.sh . + + Reason: One cannot link two owners of the same variant together because + both would offer the same functions to the linker. For that situation one + has to create a compatible variant as it is done for libisofs. + + Compatible variants may get plugged together by call combinations like + burn_set_messenger(iso_get_messenger()); + A new variant would demand a _set_messenger() function if it has to work + with libisofs. If only libburn is planned as link partner then a simple + _get_messenger() does suffice. + Take care to shutdown libburn before its provider of the *_msgs object + gets shut down. + +*/ + /* Public Opaque Handles */ /** A pointer to this is a opaque handle to a message handling facility */ @@ -86,7 +111,7 @@ struct libdax_msgs_item; /* It is well advisable to let applications select severities via strings and forwarded functions libdax_msgs__text_to_sev(), libdax_msgs__sev_to_text(). - These macros are for use by libdax/libburn only. + These macros are for use by the owner of libdax_msgs. */ /** Use this to get messages of any severity. Do not use for submitting. @@ -118,7 +143,7 @@ struct libdax_msgs_item; */ #define LIBDAX_MSGS_SEV_SORRY 0x60000000 -/** An error message which puts the whole operation of libdax in question +/** An error message which puts the whole operation of the program in question */ #define LIBDAX_MSGS_SEV_FATAL 0x70000000 @@ -134,7 +159,7 @@ struct libdax_msgs_item; /* Registered Priorities */ -/* Priorities are to be used by libburn/libdax only. */ +/* Priorities are to be selected by the programmers and not by the user. */ #define LIBDAX_MSGS_PRIO_ZERO 0x00000000 #define LIBDAX_MSGS_PRIO_LOW 0x10000000 @@ -148,7 +173,7 @@ struct libdax_msgs_item; /* Public Functions */ - /* Calls initiated from inside libdax/libburn */ + /* Calls initiated from inside the direct owner (e.g. from libburn) */ /** Create new empty message handling facility with queue. @@ -167,11 +192,11 @@ int libdax_msgs_destroy(struct libdax_msgs **m, int flag); /** Submit a message to a message handling facility. - @param driveno libdax drive number. Use -1 if no number is known. + @param driveno program specific drive number. Use -1 if no number is known. @param error_code Unique error code. Use only registered codes. See below. The same unique error_code may be issued at different occasions but those should be equivalent out of the view - of a libdax application. (E.g. "cannot open ATA drive" + of a libdax_msgs application. (E.g. "cannot open ATA drive" versus "cannot open SCSI drive" would be equivalent.) @param severity The LIBDAX_MSGS_SEV_* of the event. @param priority The LIBDAX_MSGS_PRIO_* number of the event. @@ -185,7 +210,7 @@ int libdax_msgs_submit(struct libdax_msgs *m, int driveno, int error_code, int os_errno, int flag); - /* Calls from applications (to be forwarded by libdax/libburn) */ + /* Calls from applications (to be forwarded by direct owner) */ /** Convert a registered severity number into a severity name