Prepared for neat sed translation. Explained concept of libdax_msgs variants.

This commit is contained in:
Thomas Schmitt 2007-09-15 17:16:49 +00:00
parent 635530b05e
commit 15b9f786c8
2 changed files with 33 additions and 8 deletions

View File

@ -1 +1 @@
#define Cdrskin_timestamP "2007.09.15.112311"
#define Cdrskin_timestamP "2007.09.15.171844"

View File

@ -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