Added an error message handling facility (ticket 74)

This commit is contained in:
Thomas Schmitt 2006-09-24 17:16:01 +00:00
parent 6e01855f40
commit bcaf610800
8 changed files with 857 additions and 2 deletions

View File

@ -26,6 +26,8 @@ libburn_libburn_la_SOURCES = \
libburn/lec.c \
libburn/lec.h \
libburn/libburn.h \
libburn/libdax_msgs.h \
libburn/libdax_msgs.c \
libburn/message.c \
libburn/message.h \
libburn/mmc.c \

View File

@ -166,6 +166,7 @@ or
#define Cdrskin_libburn_has_is_enumerablE 1
#define Cdrskin_libburn_has_convert_fs_adR 1
#define Cdrskin_libburn_has_convert_scsi_adR 1
#define Cdrskin_libburn_has_burn_msgS 1
#endif
#ifndef Cdrskin_libburn_versioN
@ -1280,7 +1281,7 @@ int Cdrpreskin_destroy(struct CdrpreskiN **preskin, int flag)
int Cdrpreskin__cdrecord_to_dev(char *adr, char device_adr[Cdrskin_adrleN],
int *driveno, int flag)
{
int comma_seen= 0,digit_seen= 0,busno= 0,k,lun_no= -1,ret= 0;
int comma_seen= 0,digit_seen= 0,busno= 0,k,lun_no= -1;
*driveno= -1;
device_adr[0]= 0;
@ -1344,6 +1345,8 @@ int Cdrpreskin__cdrecord_to_dev(char *adr, char device_adr[Cdrskin_adrleN],
#ifdef Cdrskin_libburn_has_convert_scsi_adR
} else {
int ret;
ret= burn_drive_convert_scsi_adr(busno,-1,*driveno,lun_no,device_adr);
return(ret);
#endif
@ -4464,6 +4467,10 @@ int Cdrskin_create(struct CdrskiN **o, struct CdrpreskiN **preskin,
}
*lib_initialized= 1;
#ifdef Cdrskin_libburn_has_burn_msgS
burn_msgs_set_severities("NEVER","SORRY","cdrskin: ");
#endif
#ifndef Cdrskin_libburn_no_burn_preset_device_opeN
burn_preset_device_open((*preskin)->drive_exclusive,
(*preskin)->drive_blocking,

View File

@ -1 +1 @@
#define Cdrskin_timestamP "2006.09.23.183608"
#define Cdrskin_timestamP "2006.09.24.171706"

View File

@ -7,6 +7,7 @@
debug_opts=
def_opts=
libvers="-DCdrskin_libburn_0_2_3"
libdax_msgs_o="libburn/libdax_msgs.o"
do_strip=0
static_opts=
warn_opts="-Wall"
@ -22,12 +23,15 @@ do
elif test "$i" = "-cvs_A60220"
then
libvers="-DCdrskin_libburn_cvs_A60220_tS"
libdax_msgs_o=
elif test "$i" = "-libburn_0_2_2"
then
libvers="-DCdrskin_libburn_0_2_2"
libdax_msgs_o=
elif test "$i" = "-libburn_0_2_3"
then
libvers="-DCdrskin_libburn_0_2_3"
libdax_msgs_o="libburn/libdax_msgs.o"
elif test "$i" = "-newapi" -o "$i" = "-experimental"
then
def_opts="$def_opts -DCdrskin_new_api_tesT"
@ -103,6 +107,7 @@ then
libburn/message.o \
libburn/sg.o \
libburn/write.o \
$libdax_msgs_o \
\
libburn/mmc.o \
libburn/sbc.o \

View File

@ -4,6 +4,8 @@
#include <assert.h>
#include <stdio.h>
#include <signal.h>
#include <string.h>
#include "init.h"
#include "sg.h"
#include "error.h"
@ -14,6 +16,11 @@
#define BURN_BACK_HACKS_INIT 1
#include "back_hacks.h"
/* ts A60924 : a new message handling facility */
#include "libdax_msgs.h"
static struct libdax_msgs *libdax_messenger= NULL;
int burn_running = 0;
/* ts A60813 : wether to use O_EXCL and/or O_NONBLOCK in libburn/sg.c */
@ -31,11 +38,21 @@ int burn_sg_open_o_nonblock = 1;
int burn_sg_open_abort_busy = 0;
/* ts A60924 : ticket 74 : Added use of global libdax_messenger */
int burn_initialize(void)
{
int ret;
if (burn_running)
return 1;
ret = libdax_msgs_new(&libdax_messenger,0);
if (ret <= 0)
return 0;
/* A60924: Apps enable queueing via burn_msgs_set_severities() */
libdax_msgs_set_severities(libdax_messenger, LIBDAX_MSGS_SEV_NEVER,
LIBDAX_MSGS_SEV_FATAL, "libburn: ", 0);
burn_running = 1;
return 1;
}
@ -49,6 +66,9 @@ void burn_finish(void)
/* ts A60904 : ticket 62, contribution by elmom : name addon "_all" */
burn_drive_free_all();
/* ts A60924 : ticket 74 */
libdax_msgs_destroy(&libdax_messenger,0);
burn_running = 0;
}
@ -78,3 +98,91 @@ void burn_preset_device_open(int exclusive, int blocking, int abort_on_busy)
burn_sg_open_abort_busy= !!abort_on_busy;
}
/* ts A60924 : ticket 74 */
/** Control queueing and stderr printing of messages from libburn.
Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
"NOTE", "UPDATE", "DEBUG", "ALL".
@param queue_severity Gives the minimum limit for messages to be queued.
Default: "NEVER". If you queue messages then you
must consume them by burn_msgs_obtain().
@param print_severity Does the same for messages to be printed directly
to stderr.
@param print_id A text prefix to be printed before the message.
@return >0 for success, <=0 for error
*/
int burn_msgs_set_severities(char *queue_severity,
char *print_severity, char *print_id)
{
int ret, queue_sevno, print_sevno;
ret = libdax_msgs__text_to_sev(queue_severity, &queue_sevno, 0);
if (ret <= 0)
return 0;
ret = libdax_msgs__text_to_sev(print_severity, &print_sevno, 0);
if (ret <= 0)
return 0;
ret = libdax_msgs_set_severities(libdax_messenger, queue_sevno,
print_sevno, print_id, 0);
if (ret <= 0)
return 0;
return 1;
}
/* ts A60924 : ticket 74 */
#define BURM_MSGS_MESSAGE_LEN 4096
/** Obtain the oldest pending libburn message from the queue which has at
least the given minimum_severity. This message and any older message of
lower severity will get discarded from the queue and is then lost forever.
Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
"NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER"
will discard the whole queue.
@param error_code Will become a unique error code as liste in
libburn/libdax_msgs.h
@param msg_text Must provide at least BURM_MSGS_MESSAGE_LEN bytes.
@param os_errno Will become the eventual errno related to the message
@param severity Will become the severity related to the message and
should provide at least 80 bytes.
@return 1 if a matching item was found, 0 if not, <0 for severe errors
*/
int burn_msgs_obtain(char *minimum_severity,
int *error_code, char msg_text[], int *os_errno,
char severity[])
{
int ret, minimum_sevno, sevno, priority;
char *textpt, *sev_name;
struct libdax_msgs_item *item = NULL;
ret = libdax_msgs__text_to_sev(minimum_severity, &minimum_sevno, 0);
if (ret <= 0)
return 0;
ret = libdax_msgs_obtain(libdax_messenger, &item, minimum_sevno,
LIBDAX_MSGS_PRIO_ZERO, 0);
if (ret <= 0)
goto ex;
ret = libdax_msgs_item_get_msg(item, error_code, &textpt, os_errno, 0);
if (ret <= 0)
goto ex;
strncpy(msg_text, textpt, BURM_MSGS_MESSAGE_LEN-1);
if(strlen(textpt) >= BURM_MSGS_MESSAGE_LEN)
msg_text[BURM_MSGS_MESSAGE_LEN-1] = 0;
severity[0]= 0;
ret = libdax_msgs_item_get_rank(item, &sevno, &priority, 0);
if(ret <= 0)
goto ex;
ret = libdax_msgs__sev_to_text(sevno, &sev_name, 0);
if(ret <= 0)
goto ex;
strcpy(severity,sev_name);
ret = 1;
ex:
libdax_msgs_destroy_item(libdax_messenger, &item, 0);
return ret;
}

View File

@ -1072,6 +1072,45 @@ int burn_session_get_hidefirst(struct burn_session *session);
*/
void burn_version(int *major, int *minor, int *micro);
/* ts A60924 : ticket 74 */
/** Control queueing and stderr printing of messages from libburn.
Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
"NOTE", "UPDATE", "DEBUG", "ALL".
@param queue_severity Gives the minimum limit for messages to be queued.
Default: "NEVER". If you queue messages then you
must consume them by burn_msgs_obtain().
@param print_severity Does the same for messages to be printed directly
to stderr.
@param print_id A text prefix to be printed before the message.
@return >0 for success, <=0 for error
*/
int burn_msgs_set_severities(char *queue_severity,
char *print_severity, char *print_id);
/* ts A60924 : ticket 74 */
#define BURM_MSGS_MESSAGE_LEN 4096
/** Obtain the oldest pending libburn message from the queue which has at
least the given minimum_severity. This message and any older message of
lower severity will get discarded from the queue and is then lost forever.
Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
"NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER"
will discard the whole queue.
@param error_code Will become a unique error code as liste in
libburn/libdax_msgs.h
@param msg_text Must provide at least BURM_MSGS_MESSAGE_LEN bytes.
@param os_errno Will become the eventual errno related to the message
@param severity Will become the severity related to the message and
should provide at least 80 bytes.
@return 1 if a matching item was found, 0 if not, <0 for severe errors
*/
int burn_msgs_obtain(char *minimum_severity,
int *error_code, char msg_text[], int *os_errno,
char severity[]);
#ifndef DOXYGEN
BURN_END_DECLS

364
libburn/libdax_msgs.c Normal file
View File

@ -0,0 +1,364 @@
/* libdax_msgs
Message handling facility of libdax.
Copyright (C) 2006 Thomas Schmitt <scdbackup@gmx.net>, provided under GPL
*/
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <string.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/time.h>
/* Only this single source module is entitled to do this */
#define LIBDAX_MSGS_H_INTERNAL 1
/* All participants in the messaging system must do this */
#include "libdax_msgs.h"
/* ----------------------------- libdax_msgs_item ------------------------- */
static int libdax_msgs_item_new(struct libdax_msgs_item **item,
struct libdax_msgs_item *link, int flag)
{
int ret;
struct libdax_msgs_item *o;
struct timeval tv;
struct timezone tz;
(*item)= o=
(struct libdax_msgs_item *) malloc(sizeof(struct libdax_msgs_item));
if(o==NULL)
return(-1);
o->timestamp= 0.0;
ret= gettimeofday(&tv,&tz);
if(ret==0)
o->timestamp= tv.tv_sec+0.000001*tv.tv_usec;
o->process_id= getpid();
o->driveno= -1;
o->severity= LIBDAX_MSGS_SEV_ALL;
o->priority= LIBDAX_MSGS_PRIO_ZERO;
o->error_code= 0;
o->msg_text= NULL;
o->os_errno= 0;
o->prev= link;
o->next= NULL;
if(link!=NULL) {
if(link->next!=NULL) {
link->next->prev= o;
o->next= link->next;
}
link->next= o;
}
return(1);
}
int libdax_msgs_item_destroy(struct libdax_msgs_item **item,
int flag)
{
struct libdax_msgs_item *o;
o= *item;
if(o==NULL)
return(0);
if(o->msg_text!=NULL)
free((char *) o->msg_text);
if(o->prev!=NULL)
o->prev->next= o->next;
if(o->next!=NULL)
o->next->prev= o->prev;
free((char *) o);
*item= NULL;
return(1);
}
int libdax_msgs_item_get_msg(struct libdax_msgs_item *item,
int *error_code, char **msg_text, int *os_errno,
int flag)
{
*error_code= item->error_code;
*msg_text= item->msg_text;
*os_errno= item->os_errno;
return(1);
}
int libdax_msgs_item_get_origin(struct libdax_msgs_item *item,
double *timestamp, pid_t *process_id, int *driveno,
int flag)
{
*timestamp= item->timestamp;
*process_id= item->process_id;
*driveno= item->driveno;
return(1);
}
int libdax_msgs_item_get_rank(struct libdax_msgs_item *item,
int *severity, int *priority, int flag)
{
*severity= item->severity;
*priority= item->priority;
return(1);
}
/* ------------------------------- libdax_msgs ---------------------------- */
int libdax_msgs_new(struct libdax_msgs **m, int flag)
{
struct libdax_msgs *o;
(*m)= o= (struct libdax_msgs *) malloc(sizeof(struct libdax_msgs));
if(o==NULL)
return(-1);
o->oldest= NULL;
o->youngest= NULL;
o->count= 0;
o->queue_severity= LIBDAX_MSGS_SEV_ALL;
o->print_severity= LIBDAX_MSGS_SEV_NEVER;
strcpy(o->print_id,"libdax: ");
#ifndef LIBDAX_MSGS_SINGLE_THREADED
pthread_mutex_init(&(o->lock_mutex),NULL);
#endif
return(1);
}
int libdax_msgs_destroy(struct libdax_msgs **m, int flag)
{
struct libdax_msgs *o;
struct libdax_msgs_item *item, *next_item;
o= *m;
if(o==NULL)
return(0);
#ifndef LIBDAX_MSGS_SINGLE_THREADED
if(pthread_mutex_destroy(&(o->lock_mutex))!=0) {
pthread_mutex_unlock(&(o->lock_mutex));
pthread_mutex_destroy(&(o->lock_mutex));
}
#endif
for(item= o->oldest; item!=NULL; item= next_item) {
next_item= item->next;
libdax_msgs_item_destroy(&item,0);
}
free((char *) o);
*m= NULL;
return(1);
}
int libdax_msgs_set_severities(struct libdax_msgs *m, int queue_severity,
int print_severity, char *print_id, int flag)
{
m->queue_severity= queue_severity;
m->print_severity= print_severity;
strncpy(m->print_id,print_id,80);
m->print_id[80]= 0;
return(1);
}
static int libdax_msgs_lock(struct libdax_msgs *m, int flag)
{
#ifndef LIBDAX_MSGS_SINGLE_THREADED
int ret;
ret= pthread_mutex_lock(&(m->lock_mutex));
if(ret!=0)
return(0);
#endif
return(1);
}
static int libdax_msgs_unlock(struct libdax_msgs *m, int flag)
{
#ifndef LIBDAX_MSGS_SINGLE_THREADED
int ret;
ret= pthread_mutex_unlock(&(m->lock_mutex));
if(ret!=0)
return(0);
#endif
return(1);
}
int libdax_msgs__text_to_sev(char *severity_name, int *severity,
int flag)
{
if(strncmp(severity_name,"NEVER",5)==0)
*severity= LIBDAX_MSGS_SEV_NEVER;
else if(strncmp(severity_name,"FATAL",5)==0)
*severity= LIBDAX_MSGS_SEV_FATAL;
else if(strncmp(severity_name,"SORRY",5)==0)
*severity= LIBDAX_MSGS_SEV_SORRY;
else if(strncmp(severity_name,"WARNING",7)==0)
*severity= LIBDAX_MSGS_SEV_WARNING;
else if(strncmp(severity_name,"HINT",4)==0)
*severity= LIBDAX_MSGS_SEV_HINT;
else if(strncmp(severity_name,"NOTE",4)==0)
*severity= LIBDAX_MSGS_SEV_NOTE;
else if(strncmp(severity_name,"UPDATE",6)==0)
*severity= LIBDAX_MSGS_SEV_UPDATE;
else if(strncmp(severity_name,"DEBUG",5)==0)
*severity= LIBDAX_MSGS_SEV_DEBUG;
else if(strncmp(severity_name,"ALL",3)==0)
*severity= LIBDAX_MSGS_SEV_ALL;
else {
*severity= LIBDAX_MSGS_SEV_NEVER;
return(0);
}
return(1);
}
int libdax_msgs__sev_to_text(int severity, char **severity_name,
int flag)
{
if(flag&1) {
*severity_name=
"NEVER\nFATAL\nSORRY\nWARNING\nHINT\nNOTE\nUPDATE\nDEBUG\nALL";
return(1);
}
*severity_name= "";
if(severity>=LIBDAX_MSGS_SEV_NEVER)
*severity_name= "NEVER";
else if(severity>=LIBDAX_MSGS_SEV_FATAL)
*severity_name= "FATAL";
else if(severity>=LIBDAX_MSGS_SEV_SORRY)
*severity_name= "SORRY";
else if(severity>=LIBDAX_MSGS_SEV_WARNING)
*severity_name= "WARNING";
else if(severity>=LIBDAX_MSGS_SEV_HINT)
*severity_name= "HINT";
else if(severity>=LIBDAX_MSGS_SEV_NOTE)
*severity_name= "NOTE";
else if(severity>=LIBDAX_MSGS_SEV_UPDATE)
*severity_name= "UPDATE";
else if(severity>=LIBDAX_MSGS_SEV_DEBUG)
*severity_name= "DEBUG";
else if(severity>=LIBDAX_MSGS_SEV_ALL)
*severity_name= "ALL";
else {
*severity_name= "";
return(0);
}
return(1);
}
int libdax_msgs_submit(struct libdax_msgs *m, int driveno, int error_code,
int severity, int priority, char *msg_text,
int os_errno, int flag)
{
int ret;
char *textpt,*sev_name,sev_text[81];
struct libdax_msgs_item *item= NULL;
if(severity >= m->print_severity) {
if(msg_text==NULL)
textpt= "";
else
textpt= msg_text;
sev_text[0]= 0;
ret= libdax_msgs__sev_to_text(severity,&sev_name,0);
if(ret>0)
sprintf(sev_text,"%s : ",sev_name);
fprintf(stderr,"%s%s%s\n",m->print_id,sev_text,textpt);
if(os_errno!=0)
perror(m->print_id);
}
if(severity < m->queue_severity)
return(0);
ret= libdax_msgs_lock(m,0);
if(ret<=0)
return(-1);
ret= libdax_msgs_item_new(&item,m->youngest,0);
if(ret<=0)
goto failed;
item->driveno= driveno;
item->error_code= error_code;
item->severity= severity;
item->priority= priority;
if(msg_text!=NULL) {
item->msg_text= malloc(strlen(msg_text)+1);
if(item->msg_text==NULL)
goto failed;
strcpy(item->msg_text,msg_text);
}
item->os_errno= os_errno;
m->youngest= item;
m->count++;
libdax_msgs_unlock(m,0);
return(1);
failed:;
libdax_msgs_item_destroy(&item,0);
libdax_msgs_unlock(m,0);
return(-1);
}
int libdax_msgs_obtain(struct libdax_msgs *m, struct libdax_msgs_item **item,
int severity, int priority, int flag)
{
int ret;
struct libdax_msgs_item *im, *next_im= NULL;
ret= libdax_msgs_lock(m,0);
if(ret<=0)
return(-1);
for(im= m->oldest; im!=NULL; im= next_im) {
for(; im!=NULL; im= next_im) {
next_im= im->next;
if(im->severity>=severity)
break;
libdax_msgs_item_destroy(&im,0); /* severity too low: delete */
}
if(im==NULL)
break;
if(im->priority>=priority)
break;
}
if(im==NULL)
{ret= 0; goto ex;}
*item= im;
ret= 1;
ex:;
libdax_msgs_unlock(m,0);
return(ret);
}
int libdax_msgs_destroy_item(struct libdax_msgs *m,
struct libdax_msgs_item **item, int flag)
{
int ret;
ret= libdax_msgs_lock(m,0);
if(ret<=0)
return(-1);
ret= libdax_msgs_item_destroy(item,0);
libdax_msgs_unlock(m,0);
return(ret);
}

330
libburn/libdax_msgs.h Normal file
View File

@ -0,0 +1,330 @@
/* libdax_msgs
Message handling facility of libdax.
Copyright (C) 2006 Thomas Schmitt <scdbackup@gmx.net>, provided under GPL
*/
/*
*Never* set this macro outside libdax_msgs.c !
The entrails of the message handling facility are not to be seen by
the other library components or the applications.
*/
#ifdef LIBDAX_MSGS_H_INTERNAL
#ifndef LIBDAX_MSGS_SINGLE_THREADED
#include <pthread.h>
#endif
struct libdax_msgs_item {
double timestamp;
pid_t process_id;
int driveno;
int severity;
int priority;
/* Apply for your developer's error code range at
libburn-hackers@pykix.org
Report introduced codes in the list below. */
int error_code;
char *msg_text;
int os_errno;
struct libdax_msgs_item *prev,*next;
};
struct libdax_msgs {
struct libdax_msgs_item *oldest;
struct libdax_msgs_item *youngest;
int count;
int queue_severity;
int print_severity;
char print_id[81];
#ifndef LIBDAX_MSGS_SINGLE_THREADED
pthread_mutex_t lock_mutex;
#endif
};
#endif /* LIBDAX_MSGS_H_INTERNAL */
#ifndef LIBDAX_MSGS_H_INCLUDED
#define LIBDAX_MSGS_H_INCLUDED 1
#ifndef LIBDAX_MSGS_H_INTERNAL
/* Public Opaque Handles */
/** A pointer to this is a opaque handle to a message handling facility */
struct libdax_msgs;
/** A pointer to this is a opaque handle to a single message item */
struct libdax_msgs_item;
#endif /* ! LIBDAX_MSGS_H_INTERNAL */
/* Public Macros */
/* Registered Severities */
/* 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.
*/
/** Use this to get messages of any severity. Do not use for submitting.
*/
#define LIBDAX_MSGS_SEV_ALL 0x00000000
/** Debugging messages not to be visible to normal users by default
*/
#define LIBDAX_MSGS_SEV_DEBUG 0x10000000
/** Update of a progress report about long running actions
*/
#define LIBDAX_MSGS_SEV_UPDATE 0x20000000
/** Not so usual events which were gracefully handled
*/
#define LIBDAX_MSGS_SEV_NOTE 0x30000000
/** Possibilities to achieve a better result
*/
#define LIBDAX_MSGS_SEV_HINT 0x40000000
/** Warnings about problems which could not be handled optimally
*/
#define LIBDAX_MSGS_SEV_WARNING 0x50000000
/** Non-fatal error messages indicating that parts of the action failed
but processing will/should go on
*/
#define LIBDAX_MSGS_SEV_SORRY 0x60000000
/** An error message which puts the whole operation of libdax in question
*/
#define LIBDAX_MSGS_SEV_FATAL 0x70000000
/** A severity to exclude resp. discard any possible message.
Do not use this severity for submitting.
*/
#define LIBDAX_MSGS_SEV_NEVER 0x7fffffff
/* Registered Priorities */
/* Priorities are to be used by libburn/libdax only. */
#define LIBDAX_MSGS_PRIO_ZERO 0x00000000
#define LIBDAX_MSGS_PRIO_LOW 0x10000000
#define LIBDAX_MSGS_PRIO_MEDIUM 0x20000000
#define LIBDAX_MSGS_PRIO_HIGH 0x30000000
#define LIBDAX_MSGS_PRIO_TOP 0x7ffffffe
/* Do not use this priority for submitting */
#define LIBDAX_MSGS_PRIO_NEVER 0x7fffffff
/* Public Functions */
/* Calls initiated from inside libdax/libburn */
/** Create new empty message handling facility with queue.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return >0 success, <=0 failure
*/
int libdax_msgs_new(struct libdax_msgs **m, int flag);
/** Destroy a message handling facility and all its eventual messages.
The submitted pointer gets set to NULL.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 for success, 0 for pointer to NULL
*/
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 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"
versus "cannot open SCSI drive" would be equivalent.)
@param severity The LIBDAX_MSGS_SEVERITY_* of the event.
@param priority The LIBDAX_MSGS_PRIORITY_* number of the event.
@param msg_text Printable and human readable message text.
@param os_errno Eventual error code from operating system (0 if none)
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 on success, 0 on rejection, <0 for severe errors
*/
int libdax_msgs_submit(struct libdax_msgs *m, int driveno, int error_code,
int severity, int priority, char *msg_text,
int os_errno, int flag);
/* Calls from applications (to be forwarded by libdax/libburn) */
/** Convert a registered severity number into a severity name
@param flag Bitfield for control purposes:
bit0= list all severity names in a newline separated string
@return >0 success, <=0 failure
*/
int libdax_msgs__sev_to_text(int severity, char **severity_name,
int flag);
/** Convert a severity name into a severity number,
@param flag Bitfield for control purposes (unused yet, submit 0)
@return >0 success, <=0 failure
*/
int libdax_msgs__text_to_sev(char *severity_name, int *severity,
int flag);
/** Set minimum severity for messages to be queued (default
LIBDAX_MSGS_SEV_ALL) and for messages to be printed directly to stderr
(default LIBDAX_MSGS_SEV_NEVER).
@param print_id A text of at most 80 characters to be printed before
any eventually printed message (default is "libdax: ").
@param flag Bitfield for control purposes (unused yet, submit 0)
@return always 1 for now
*/
int libdax_msgs_set_severities(struct libdax_msgs *m, int queue_severity,
int print_severity, char *print_id, int flag);
/** Obtain a message item that has at least the given severity and priority.
Usually all older messages of lower severity are discarded then. If no
item of sufficient severity was found, all others are discarded from the
queue.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 if a matching item was found, 0 if not, <0 for severe errors
*/
int libdax_msgs_obtain(struct libdax_msgs *m, struct libdax_msgs_item **item,
int severity, int priority, int flag);
/** Destroy a message item obtained by libdax_msgs_obtain(). The submitted
pointer gets set to NULL.
Caution: Copy eventually obtained msg_text before destroying the item,
if you want to use it further.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 for success, 0 for pointer to NULL, <0 for severe errors
*/
int libdax_msgs_destroy_item(struct libdax_msgs *m,
struct libdax_msgs_item **item, int flag);
/** Obtain from a message item the three application oriented components as
submitted with the originating call of libdax_msgs_submit().
Caution: msg_text becomes a pointer into item, not a copy.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 on success, 0 on invalid item, <0 for servere errors
*/
int libdax_msgs_item_get_msg(struct libdax_msgs_item *item,
int *error_code, char **msg_text, int *os_errno,
int flag);
/** Obtain from a message item the submitter identification submitted
with the originating call of libdax_msgs_submit().
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 on success, 0 on invalid item, <0 for servere errors
*/
int libdax_msgs_item_get_origin(struct libdax_msgs_item *item,
double *timestamp, pid_t *process_id, int *driveno,
int flag);
/** Obtain from a message item severity and priority as submitted
with the originating call of libdax_msgs_submit().
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 on success, 0 on invalid item, <0 for servere errors
*/
int libdax_msgs_item_get_rank(struct libdax_msgs_item *item,
int *severity, int *priority, int flag);
#ifdef LIDBAX_MSGS_________________
/* Registered Error Codes */
Format: error_code (LIBDAX_MSGS_SEV_*,LIBDAX_MSGS_PRIO_*) = explanation
If no severity or priority are fixely associates, use "(,)".
------------------------------------------------------------------------------
Range "libdax_msgs" : 0x00000000 to 0x0000ffff
0x0000 (ALL,ZERO) = Initial setting in new libdax_msgs_item
0x0001 (DEBUG,ZERO) = Test error message
------------------------------------------------------------------------------
Range "elmom" : 0x00010000 to 0x0001ffff
------------------------------------------------------------------------------
Range "scdbackup" : 0x00020000 to 0x0002ffff
------------------------------------------------------------------------------
#endif /* LIDBAX_MSGS_________________ */
#ifdef LIBDAX_MSGS_H_INTERNAL
/* Internal Functions */
/** Lock before doing side effect operations on m */
static int libdax_msgs_lock(struct libdax_msgs *m, int flag);
/** Unlock after effect operations on m are done */
static int libdax_msgs_unlock(struct libdax_msgs *m, int flag);
/** Create new empty message item.
@param link Previous item in queue
@param flag Bitfield for control purposes (unused yet, submit 0)
@return >0 success, <=0 failure
*/
static int libdax_msgs_item_new(struct libdax_msgs_item **item,
struct libdax_msgs_item *link, int flag);
/** Destroy a message item obtained by libdax_msgs_obtain(). The submitted
pointer gets set to NULL.
@param flag Bitfield for control purposes (unused yet, submit 0)
@return 1 for success, 0 for pointer to NULL
*/
static int libdax_msgs_item_destroy(struct libdax_msgs_item **item, int flag);
#endif /* LIBDAX_MSGS_H_INTERNAL */
#endif /* ! LIBDAX_MSGS_H_INCLUDED */