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