include/realmedia/rmaerror.h

   1 /****************************************************************************
   2  *
   3  *  $Id: rmaerror.h 7 2003-05-30 02:18:02Z gabest $
   4  *
   5  *  Copyright (C) 1995-1999 RealNetworks, Inc. All rights reserved.
   6  *
   7  *  http://www.real.com/devzone
   8  *
   9  *  This program contains proprietary
  10  *  information of Progressive Networks, Inc, and is licensed
  11  *  subject to restrictions on use and distribution.
  12  *
  13  *
  14  *  RealMedia Architecture error reporting interfaces.
  15  *
  16  */
  17
  18 #ifndef _RMAERROR_H_
  19 #define _RMAERROR_H_
  20
  21 /*
  22  * Forward declarations of some interfaces defined here-in.
  23  */
  24 typedef _INTERFACE       IRMABuffer                 IRMABuffer;
  25 typedef _INTERFACE       IRMAErrorSinkControl       IRMAErrorSinkControl;
  26
  27
  28 /* Message Severity values */
  29
  30 enum {
  31      PNLOG_EMERG     = 0, /* A panic condition.  Server / Player will halt or
  32                              restart. */
  33
  34      PNLOG_ALERT     = 1, /* A condition that should be corrected immediately.
  35                              Needs user intervention to prevent problems. */
  36
  37      PNLOG_CRIT      = 2, /* Critical conditions. */
  38
  39      PNLOG_ERR       = 3, /* Errors. */
  40
  41      PNLOG_WARNING   = 4, /* Warning messages. */
  42
  43      PNLOG_NOTICE    = 5, /* Conditions that are not error conditions, but
  44                              should possibly be handled specially. */
  45
  46      PNLOG_INFO      = 6, /* Informational messages. */
  47
  48      PNLOG_DEBUG     = 7  /* Messages that contain information normally of use
  49                              only when debugging a program. */
  50 };
  51
  52
  53 /****************************************************************************
  54  *
  55  *  Interface:
  56  *
  57  *      IRMAErrorMessages
  58  *
  59  *  Purpose:
  60  *
  61  *      Error, event, and status message reporting interface
  62  *
  63  *  IID_IRMAErrorMessages:
  64  *
  65  *      {00000800-0901-11d1-8B06-00A024406D59}
  66  *
  67  */
  68 DEFINE_GUID(IID_IRMAErrorMessages, 0x00000800, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
  69                         0xa0, 0x24, 0x40, 0x6d, 0x59);
  70
  71 #undef  INTERFACE
  72 #define INTERFACE   IRMAErrorMessages
  73
  74 DECLARE_INTERFACE_(IRMAErrorMessages, IUnknown)
  75 {
  76     /*
  77      *  IUnknown methods
  78      */
  79     STDMETHOD(QueryInterface)   (THIS_
  80                                 REFIID riid,
  81                                 void** ppvObj) PURE;
  82
  83     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
  84
  85     STDMETHOD_(ULONG,Release)   (THIS) PURE;
  86
  87     /*
  88      *  IRMAErrorMessages methods
  89      */
  90
  91     /************************************************************************
  92      *  Method:
  93      *      IRMAErrorMessages::Report
  94      *  Purpose:
  95      *      Call this method to report an error, event, or status message.
  96      *  Parameters:
  97      *
  98      *      const UINT8 unSeverity
  99      *      Type of report. This value will impact how the player, tool, or
 100      *      server will react to the report. Possible values are described
 101      *      above. Depending on the error type, an error message with the
 102      *      RMA code, anda string translation of that code will be displayed.
 103      *      The error dialog includes a "more info" section that displays the
 104      *      user code and string, and a link to the more info URL. In the
 105      *      server these messages are logged to the log file.
 106      *
 107      *      const ULONG32   ulRMACode
 108      *      Well known RMA error code. This will be translated to a text
 109      *      representation for display in an error dialog box or log file.
 110      *
 111      *      const ULONG32   ulUserCode
 112      *      User specific error code. This will NOT be translated to a text
 113      *      representation. This can be any value the caller wants, it will
 114      *      be logged or displayed but not interpretted.
 115      *
 116      *      const char*     pUserString
 117      *      User specific error string. This will NOT be translated or
 118      *      modified. This can be any value the caller wants, it will
 119      *      be logged or displayed but not interpretted.
 120      *
 121      *      const char*     pMoreInfoURL
 122      *      User specific more info URL string.
 123      *
 124      */
 125     STDMETHOD(Report)           (THIS_
 126                                 const UINT8     unSeverity,
 127                                 PN_RESULT       ulRMACode,
 128                                 const ULONG32   ulUserCode,
 129                                 const char*     pUserString,
 130                                 const char*     pMoreInfoURL) PURE;
 131
 132     /************************************************************************
 133      *  Method:
 134      *      IRMAErrorMessages::GetErrorText
 135      *  Purpose:
 136      *      Call this method to get the text description of a RMA error code.
 137      *  Parameters:
 138      *      PN_RESULT ulRMACode (A RMA error code)
 139      *  Return Value:
 140      *      IRMABuffer* containing error text.
 141      */
 142     STDMETHOD_(IRMABuffer*, GetErrorText)       (THIS_
 143                                                 PN_RESULT       ulRMACode) PURE;
 144 };
 145
 146
 147 /****************************************************************************
 148  *
 149  *  Interface:
 150  *
 151  *      IRMAErrorSink
 152  *
 153  *  Purpose:
 154  *
 155  *      Error Sink Interface
 156  *
 157  *  IID_IRMAErrorSink:
 158  *
 159  *      {00000801-0901-11d1-8B06-00A024406D59}
 160  *
 161  */
 162 DEFINE_GUID(IID_IRMAErrorSink, 0x00000801, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 163                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 164
 165 #undef  INTERFACE
 166 #define INTERFACE   IRMAErrorSink
 167
 168 DECLARE_INTERFACE_(IRMAErrorSink, IUnknown)
 169 {
 170     /*
 171      *  IUnknown methods
 172      */
 173     STDMETHOD(QueryInterface)   (THIS_
 174                                 REFIID riid,
 175                                 void** ppvObj) PURE;
 176
 177     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 178
 179     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 180
 181     /*
 182      *  IRMAErrorSink methods
 183      */
 184
 185     /************************************************************************
 186      *  Method:
 187      *      IRMAErrorSink::ErrorOccurred
 188      *  Purpose:
 189      *      After you have registered your error sink with an
 190      *      IRMAErrorSinkControl (either in the server or player core) this
 191      *      method will be called to report an error, event, or status message.
 192      *
 193      *      The meaning of the arguments is exactly as described in
 194      *      rmaerror.h
 195      */
 196     STDMETHOD(ErrorOccurred)    (THIS_
 197                                 const UINT8     unSeverity,
 198                                 const ULONG32   ulRMACode,
 199                                 const ULONG32   ulUserCode,
 200                                 const char*     pUserString,
 201                                 const char*     pMoreInfoURL
 202                                 ) PURE;
 203 };
 204
 205
 206 /****************************************************************************
 207  *
 208  *  Interface:
 209  *
 210  *      IRMAErrorSinkControl
 211  *
 212  *  Purpose:
 213  *
 214  *      Error Sink Control Interface
 215  *
 216  *  IID_IRMAErrorSinkControl:
 217  *
 218  *      {00000802-0901-11d1-8B06-00A024406D59}
 219  *
 220  */
 221 DEFINE_GUID(IID_IRMAErrorSinkControl, 0x00000802, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 222                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 223
 224 #undef  INTERFACE
 225 #define INTERFACE   IRMAErrorSinkControl
 226
 227
 228 DECLARE_INTERFACE_(IRMAErrorSinkControl, IUnknown)
 229 {
 230     /*
 231      *  IUnknown methods
 232      */
 233     STDMETHOD(QueryInterface)   (THIS_
 234                                 REFIID riid,
 235                                 void** ppvObj) PURE;
 236
 237     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 238
 239     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 240
 241     /*
 242      *  IRMAErrorSinkControl methods
 243      */
 244
 245     /************************************************************************
 246      *  Method:
 247      *      IRMAErrorSinkControl::AddErrorSink
 248      *  Purpose:
 249      *      Call this method to tell the sink controller to handle an error
 250      *      sink.
 251      *
 252      *      This method also allows you to set a range of severity levels which
 253      *      you will receive reports for.
 254      *
 255      *      Note: You should specify an invalid range (Low = 1, High = 0 for
 256      *            example) if you don't want to receive any errors.
 257      *
 258      *      The default severity range is PNLOG_EMERG to PNLOG_INFO (0-6).
 259      */
 260     STDMETHOD(AddErrorSink)     (THIS_
 261                                 IRMAErrorSink*  pErrorSink,
 262                                 const UINT8     unLowSeverity,
 263                                 const UINT8     unHighSeverity) PURE;
 264
 265     /************************************************************************
 266      *  Method:
 267      *      IRMAErrorSinkControl::AddErrorSink
 268      *  Purpose:
 269      *      Call this method to remove an error sink.
 270      */
 271     STDMETHOD(RemoveErrorSink)  (THIS_
 272                                 IRMAErrorSink*  pErrorSink) PURE;
 273
 274 };
 275
 276 #endif /* _RMAERROR_H_ */