MusicKit  0.0.0
DSPError.h
00001 #ifndef __MK_DSPError_H___
00002 #define __MK_DSPError_H___
00003 /* $Id$
00004  * Functions in libdsp_s.a having to do with error handling
00005  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00006  * Author: Julius O. Smith III
00007  */
00008 
00009 /***************************** Error Enabling ********************************/
00010 
00011 extern int DSPEnableErrorLog(void);
00012 /* 
00013  * Turn on DSP error logging into the current error log file
00014  * set by DSPSetErrorFile().
00015  */
00016 
00017 
00018 extern int DSPDisableErrorLog(void);
00019 /* 
00020  * Turn off DSP error message logging.
00021  */
00022 
00023 
00024 extern int DSPErrorLogIsEnabled(void);
00025 /* 
00026  * Returns nonzero if DSP error logging is enabled.
00027  */
00028 
00029 /******************************* ERROR FILE CONTROL **************************/
00030 
00031 extern int DSPEnableErrorFile(const char *fn);
00032 /* 
00033  * Turn on DSP error message logging (equivalent to DSPEnableErrorLog())
00034  * and set the error file to fn (equivalent to DSPSetErrorFile(fn)).
00035  */
00036 
00037 
00038 extern int DSPEnableErrorFP(FILE *fp);
00039 /* 
00040  * Turn on DSP error message logging (equivalent to DSPEnableErrorLog())
00041  * and set the error file pointer to fp (equivalent to DSPSetErrorFP(fp)).
00042  */
00043 
00044 
00045 extern int DSPSetErrorFile(char *fn);
00046 /* 
00047  * Set the file-name for DSP error messages to fn.
00048  * The default file used if this is not called is
00049  * DSP_ERRORS_FILE defined in dsp.h.
00050  * This will clear any file-pointer specified using
00051  * DSPSetErrorFP().
00052  */
00053 
00054 
00055 extern char *DSPGetErrorFile(void);
00056 /* 
00057  * Get the file-name being used for DSP error messages, if known.
00058  * If unknown, such as when only a file-pointer was passed to
00059  * specify the output destination, 0 is returned.
00060  */
00061 
00062 
00063 extern int DSPSetErrorFP(FILE *fp);
00064 /* 
00065  * Set the file-pointer for DSP error messages to fp.
00066  * The file-pointer will clear and override any prior specification
00067  * of the error messages filename using DSPSetErrorFile().
00068  */
00069 
00070 
00071 extern FILE *DSPGetErrorFP(void);
00072 /* 
00073  * Get the file-pointer being used for DSP error messages.
00074  */
00075 
00076 
00077 extern int DSPCloseErrorFP(void);
00078 /*
00079  * Close DSP error log file.
00080  */
00081 
00082 
00083 /******************************* Error File Usage ****************************/
00084 
00085 
00086 extern int DSPUserError(
00087     int errorcode,
00088     char *msg);
00089 /* 
00090  * Print message string 'msg' and integer error code 'errorcode' to the
00091  * DSP error log (if any), and return errorcode.  The message string 
00092  * normally identifies the calling function and the nature of the error.
00093  * The error code is arbitrary, but positive integers are generally in
00094  * use by other packages.
00095  */
00096 
00097 
00098 extern int DSPUserError1(
00099     int errorcode,
00100     char *msg,
00101     char *str);
00102 /* 
00103  * Print message string 'msg' and integer error code 'errorcode' to the
00104  * DSP error log (if any), and return errorcode.  The message string is
00105  * assumed to contain a single occurrence of '%s' which corresponds to the
00106  * desired placement of 'str' in the style of printf().
00107  */
00108 
00109 
00110 extern char *DSPMessageExpand(int msg);
00111 /*
00112  * Convert 24-bit DSP message into a string containing mnemonic message 
00113  * opcode and argument datum in hex. Example: The DSP message 0x800040
00114  * expands into "BREAK(0x0040)" which means a breakpoint occurred in the DSP
00115  * at location 0x40.  (DSP messages are messages from the DSP to the host,
00116  * as read by DSPReadMessages().  They are not error codes returned by 
00117  * libdsp functions.)
00118  */
00119 
00120 #endif