home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audiofile / AFseterrorhandler.z / AFseterrorhandler
Encoding:
Text File  |  2002-10-03  |  4.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333ddddmmmm))))                                  aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afSetErrorHandler - supply an alternate error reporting routine to the
  10.      Audio File Library
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      AAAAFFFFeeeerrrrrrrrffffuuuunnnncccc aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((AAAAFFFFeeeerrrrrrrrffffuuuunnnncccc eeeeffffuuuunnnncccc))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  18.      _e_f_u_n_c       is a pointer to an error handling routine which is declared
  19.                  as:
  20.  
  21.                  vvvvooooiiiidddd eeeerrrrrrrroooorrrrffffuuuunnnncccc((((lllloooonnnngggg,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr****))))
  22.  
  23. RRRREEEETTTTUUUURRRRNNNNEEEEDDDD VVVVAAAALLLLUUUUEEEE
  24.      The returned value is a pointer to the previous error handling routine.
  25.  
  26. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  27.      aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(((()))) allows you to override the default error handling
  28.      routine.
  29.  
  30.      The arguments that are passed to the error handling routine are an error
  31.      code and a string containing a description of the error.
  32.  
  33. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  34.          #include <dmedia/audiofile.h>
  35.          AFerrfunc defaultErrorHandler;
  36.          void silentAFerror(long errnum, const char* fmt)
  37.          {
  38.               /* suppress AF errors here */
  39.          }
  40.          ...
  41.               /* supply a new error handler */
  42.          defaultErrorHandler = afSetErrorHandler(silentAFerror);
  43.               /* AF errors won't be reported  here */
  44.          ...
  45.               /* restore the default error handler */
  46.          afSetErrorHandler(originalErrorHandler);
  47.               /* AF errors will be reported by the default error handler */
  48.          ...
  49.  
  50. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  51.      The AF library error handler function pointer is declared as a global
  52.      variable, and therefor is not safe for use in multi-threaded
  53.      applications.  Specifically, a core dump may result if more than one
  54.      thread attempts to use the error handler simultaneously.  This can be
  55.      avoided by calling afSetErrorHandler(NULL) to disable the feature
  56.      entirely.  The current version of the AF library has a MT-safe
  57.      alternative to the AFerrorhandler:
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333ddddmmmm))))                                  aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      After disabling the internal error handler as shown above, an application
  75.      should handle errors as in the example below:
  76.      #include <dmedia/dmedia.h>
  77.  
  78.      AFfilehandle handle;
  79.  
  80.      handle = afOpenFile("some_filename", "r", NULL); /* attempt to open */
  81.  
  82.      if(handle == NULL) {
  83.          char detail[DM_MAX_ERROR_DETAIL]; /* storage for error detail */
  84.          int errorNumber;                  /* error token storage */
  85.          char *msg;                        /* short error message */
  86.          msg = dmGetError(&errorNumber, detail);
  87.          if(msg != NULL)                   /* if NULL, no error was reported */
  88.              fprintf(stderr, "%s [error number %d]\n", detail, errorNumber);
  89.  
  90.          exit(1); /* or whatever */
  91.      }
  92.      The application must add ----llllddddmmmmeeeeddddiiiiaaaa to its link list if it calls
  93.      dmGetError().  See ddddmmmmGGGGeeeettttEEEErrrrrrrroooorrrr(3dm) for more details on this alternative.
  94.  
  95. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  96.      stdarg(5), afIntro(3dm), dmIntro(3dm), dmGetError(3dm)
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.