/**************************************************************************** * * $Id: * * Copyright (C) 1998-2000 RealNetworks. * All rights reserved. * * http://www.real.com/devzone * * This program contains proprietary information of RealNetworks, Inc., * and is licensed subject to restrictions on use and distribution. * * * Main interface to the log system. Used to obtain interfaces to more * specific functionality. */ #ifndef _IRTALOGSYSTEM_H #define _IRTALOGSYSTEM_H #include enum LogCode { // Messages that application end-users or 3rd party SDK developers will see LC_APP_DIAG = 0x000000F0, // Less important/diagnostic messages (only interesting if something goes wrong) LC_APP_INFO = 0x7F000000, // Very important messages (always want to see these messages) LC_APP_WARN = 0x00FF0000, // There was a problem, but it was handled and everything is probably ok LC_APP_ERROR = 0x0000FF00, // There was a problem -- it wasn't handled // Messages that 3rd party sdk developers will see -- ok to mention IRMA interfaces LC_SDK_DIAG = 0x000000F2, // Less important/diagnostic messages (only interesting if something goes wrong) LC_SDK_INFO = 0x7f000002, // Very important messages (always want to see these messages) LC_SDK_WARN = 0x00FF0002, // There was a problem, but it was handled and everything is probably ok LC_SDK_ERROR = 0x0000FF02, // There was a problem -- it wasn't handled }; enum LogCodeFilterMask { SDK_MESSAGE_MASK = 0x00000002, DIAG_MESSAGE_MASK = 0x000000F0, ERROR_MESSAGE_MASK = 0x0000FF00, WARN_MESSAGE_MASK = 0x00FF0000, INFO_MESSAGE_MASK = 0x7F000000, }; enum FuncArea { NONE = 0, ACTIVEX, AUDCODEC, AUDPREFIL, BCAST, CAPTURE, CMDLINE, FILEOUT, FILEREAD, GUI, JOBFILE, LIC, POSFIL, PUB, REMOTE, FA_SDK_CONFIG, // SDK config objects (typically rmsession) FA_SDK_ENCODE, // SDK encoding (typically encpipeline, rulebookgen) FA_SDK_CORE, // RSCore, RSUtil, RSGraphManager stuff FA_GEN_FILTER, // Generic filter msgs STATS, VIDCODEC, VIDPREFIL, VIDRENDR, MEDIASAMPLES }; /**************************************************************************** * * Interface: * * IRTALogObserver * * Purpose: * * IID_IRTALogObserver: * * This interface must be implemented by and object registering with the log * system to receive log messages. * * // {EA6ABCF4-66EB-11d4-931A-00D0B749DE42} * */ DEFINE_GUID(IID_IRTALogObserver, 0xea6abcf4, 0x66eb, 0x11d4, 0x93, 0x1a, 0x0, 0xd0, 0xb7, 0x49, 0xde, 0x42); #undef INTERFACE #define INTERFACE IRTALogObserver DECLARE_INTERFACE_(IRTALogObserver, IUnknown) { /* * IUnknown methods */ STDMETHOD(QueryInterface) (THIS_ REFIID riid, void** ppvObj) PURE; STDMETHOD_(ULONG32,AddRef) (THIS) PURE; STDMETHOD_(ULONG32,Release) (THIS) PURE; /************************************************************************ * Method: * IRTALogObserverManager::OnEndService * Purpose: * The observer will receive this call as notification that the log system * is shutting down, and that all log messages have been delivered. * Parameters: * NONE * Returns: * Ignored. */ STDMETHOD(OnEndService) (THIS) PURE; /************************************************************************ * Method: * IRTALogObserverManager::ReceiveMsg * Purpose: * Method called on an observer when a log message is sent to the log * system that passes the observers filter. * Parameters: * szNamespace - [in] The namespace used to qualify the functional area * and translated messge. * nCode - [in] The important level of the message. * unFuncArea - [in] numeric value used in the message as the functional area * szFuncArea - [in] The translated string for the numeric functional area, if * one was found. * nTimeStamp - [in] The time (in milliseconds since midnight, Jan.1, 1970) at * which the log message was sent to the log system. * nMsg - [in] The numeric value used to identify the message for translation. * szMsg - [in] The actual message text, either translation or the text sent * to the LogMessage method. * szJobName - [in] The name of the job from which the message originated. * Returns: * Ignored. */ STDMETHOD(ReceiveMsg) (THIS_ const char* /*IN*/ szNamespace, LogCode /*IN*/ nCode, UINT32 /*IN*/ unFuncArea, const char* /*IN*/ szFuncArea, INT32 /*IN*/ nTimeStamp, UINT32 /*IN*/ nMsg, const char* /*IN*/ szMsg, const char* /*IN*/ szJobName) PURE; }; /**************************************************************************** * * Interface: * * IRTAFuncAreaEnum * * Purpose: * * This is an enumeration interface which will enurmerate through all functional * areas pre-loaded by the log system. * * IID_IRTAFuncAreaEnum: * * // {938F4A21-1327-11d5-9349-00D0B749DE42} * */ DEFINE_GUID(IID_IRTAFuncAreaEnum, 0x938f4a21, 0x1327, 0x11d5, 0x93, 0x49, 0x0, 0xd0, 0xb7, 0x49, 0xde, 0x42); #undef INTERFACE #define INTERFACE IRTAFuncAreaEnum DECLARE_INTERFACE_(IRTAFuncAreaEnum, IUnknown) { /* * IUnknown methods */ STDMETHOD(QueryInterface) (THIS_ REFIID riid, void** ppvObj) PURE; STDMETHOD_(ULONG32,AddRef) (THIS) PURE; STDMETHOD_(ULONG32,Release) (THIS) PURE; /************************************************************************ * Method: * IRTAFuncAreaEnum::GetFirst * Purpose: * Returns details about the first pre-loaded functional area and resets * the enumerator to that position. * Parameters: * ppszNamespace - [out] Pointer to the pointer which will point to the text * of the namespace for this functional area. * pnNum - [out] Pointer to the integer which will be set to the numeric value * for this functional area. * ppszName - [out] Pointer to the pointer which will be set to the localized * translation of the text representing the functional area. * Returns: * PNR_OK - If success. * PNR_FAIL - No functional areas preloaded by the log system. */ STDMETHOD (GetFirst) (THIS_ const char** /*OUT*/ ppszNamespace, UINT32* /*OUT*/ pnNum, const char** /*OUT*/ ppszName) PURE; /************************************************************************ * Method: * IRTALogObserverManager::OnEndService * Purpose: * Returns details about the next pre-loaded functional area. * Parameters: * ppszNamespace - [out] Pointer to the pointer which will point to the text * of the namespace for this functional area. * pnNum - [out] Pointer to the integer which will be set to the numeric value * for this functional area. * ppszName - [out] Pointer to the pointer which will be set to the localized * translation of the text representing the functional area. * Returns: * PNR_OK - If success. * PNR_FAIL - No more functional areas. */ STDMETHOD (GetNext) (THIS_ const char** /*OUT*/ ppszNamespace, UINT32* /*OUT*/ pnNum, const char** /*OUT*/ ppszName) PURE; }; /**************************************************************************** * * Interface: * * IRTALogObserverManager * * Purpose: * * This interface manages the subscription of observer objects to the log * system. * * IID_IRTALogObserverManager: * * // {EA6ABCDC-66EB-11d4-931A-00D0B749DE42} * */ DEFINE_GUID(IID_IRTALogObserverManager, 0xea6abcdc, 0x66eb, 0x11d4, 0x93, 0x1a, 0x0, 0xd0, 0xb7, 0x49, 0xde, 0x42); #undef INTERFACE #define INTERFACE IRTALogObserverManager DECLARE_INTERFACE_(IRTALogObserverManager, IUnknown) { /* * IUnknown methods */ STDMETHOD(QueryInterface) (THIS_ REFIID riid, void** ppvObj) PURE; STDMETHOD_(ULONG32,AddRef) (THIS) PURE; STDMETHOD_(ULONG32,Release) (THIS) PURE; /************************************************************************ * Method: * IRTALogObserverManager::Subscribe * Purpose: * Adds an observer to the log system which will receive log messages, and * initializes it with the parameter values. * Parameters: * pUnknown - [in] IUnknown pointer to the observer object which must * support a QueryInterface for the IRTALogObserver interface. * szFilterStr - [in] XML string specifying an initial filter for this * observer. * szLocale - [in] Language in which the observer wishes to receive log * messages. **Currently ignored** * bCatchup - [in] Indicates whether the observer wishes to receive all * log messages (up to 1000) previously delivered by the log system * prior to this observers subscription. * Returns: * PNR_OK - If success. * PNR_FAIL - IUnknown parameter did not support the IRTALogObserver interface. */ STDMETHOD (Subscribe) (THIS_ IUnknown* /*IN*/ pUnknown, const char* /*IN*/ szFilterStr, const char* /*IN*/ szLocale, BOOL /*IN*/ bCatchUp) PURE; /************************************************************************ * Method: * IRTALogObserverManager::SetFilter * Purpose: * Applies the specified filter to all future log messages delivered to * the specified observer. * Parameters: * szFilterStr - [in] XML string specifying a filter for this * observer. * pObserver - [in] An IUnknown pointer to a previously subscribed observer * which will have the filter applied to it. * Returns: * PNR_OK - Since the filter is applied asynchronously, the function will * Always succeed. */ STDMETHOD (SetFilter) (THIS_ const char* /*IN*/ szFilterStr, IUnknown* /*IN*/ pObserver) PURE; /************************************************************************ * Method: * IRTALogObserverManager::Unsubscribe * Purpose: * Removes an observer from the log system. * Parameters: * pUnknown - [in] IUnknown pointer to the observer object to be * removed. * bReceiveUnsentMessages - [in] Indicates whether the observer wishes * have delivered all messages which have been received by the log * system but not yet delivered to this observer. * Returns: * PNR_OK - If success. * PNR_FAIL - The specified observer was not subscribed to the log system. */ STDMETHOD (Unsubscribe) (THIS_ IUnknown* /*IN*/ pObserver, BOOL /*IN*/ bReceiveUnsentMessages) PURE; /************************************************************************ * Method: * IRTALogObserverManager::SetLanguage * Purpose: * Sets the language which will be used for translatable messages when * messages are delivered to the specified observer. * Parameters: * szLanguage - [in] Language in which the observer wishes to receive log * messages. **Currently ignored** * pObserver - [in] IUnknown pointer to the observer which will have its * language value set. * Returns: * PNR_OK - If success. * PNR_FAIL - Observer was not subscribed to the log system. */ STDMETHOD (SetLanguage) (THIS_ const char* /*IN*/ szLanguage, IUnknown* /*IN*/ pObserver) PURE; }; /**************************************************************************** * * Interface: * * IRTALogWriter * * Purpose: * * This interface is used to send log messages to the log system. * * IID_IRTALogWriter: * * {EA6ABCD9-66EB-11d4-931A-00D0B749DE42} * */ DEFINE_GUID(IID_IRTALogWriter, 0xea6abcd9, 0x66eb, 0x11d4, 0x93, 0x1a, 0x0, 0xd0, 0xb7, 0x49, 0xde, 0x42); #undef INTERFACE #define INTERFACE IRTALogWriter DECLARE_INTERFACE_(IRTALogWriter, IUnknown) { /* * IUnknown methods */ STDMETHOD(QueryInterface) (THIS_ REFIID riid, void** ppvObj) PURE; STDMETHOD_(ULONG32,AddRef) (THIS) PURE; STDMETHOD_(ULONG32,Release) (THIS) PURE; /************************************************************************ * Method: * IRTALogWriter::LogMessage * Purpose: * Logs a message in the log system with the specified parameters * to be delivered to all observers. * * Parameters: * szNamespace - [in] Text identifier to qualify the functional area * and numeric message parameter. * nLogCode - [in] Enumerated value from rtalogconstants.h which * indicates the importance of the log message * nFuncArea - [in] Enumerated value from rtalogconstnats.h which * indicates the general area of the system where the message * originated. * nMsg - [in] Identifies the log message to be used from the translation * xml files loaded by the log system upon startup. To use the * szMsg variable for the message instead, specify 0xFFFFFFFF for * this value. * szMsg - [in] Contains the text that will be used for the log message if * the nMsg parameter is 0xFFFFFFFF. * Returns: * PNR_OK - if success * PNR_FAIL - Log system is not properly initialized. */ STDMETHOD(LogMessage) (THIS_ const char* /*IN*/ szNamespace, LogCode /*IN*/ nLogCode, FuncArea /*IN*/ nFuncArea, UINT32 /*IN*/ nMsg, const char* /*IN*/ szMsg ) PURE; /************************************************************************ * Method: * IRTALogWriter::GetTranslatedMessage * Purpose: * Retrieves the translated string for the message number provided * from the log system. * * Parameters: * nMessageNumber - [in] Message number to be translated. * szNamespace - [in] Namespace of the message to be translated. * szLanguage - [in] Currently unused. * szMessage - [out] Translated message string. * Returns: * PNR_OK - if success */ STDMETHOD(GetTranslatedMessage) (THIS_ UINT32 /*IN*/ nMessageNumber, const char* /*IN*/ szNamespace, const char* /*IN*/ szLanguage, const char** /*OUT*/ szMessage ) PURE; }; /**************************************************************************** * * Interface: * * IRTALogSystem * * Purpose: * Provides access to the areas of the log system * * IID_IRTALogSystem: * * // {E50F7E51-4640-11d5-935B-00D0B749DE42} * */ DEFINE_GUID(IID_IRTALogSystem, 0xe50f7e51, 0x4640, 0x11d5, 0x93, 0x5b, 0x0, 0xd0, 0xb7, 0x49, 0xde, 0x42); #undef INTERFACE #define INTERFACE IRTALogSystem DECLARE_INTERFACE_(IRTALogSystem, IUnknown) { /* * IUnknown methods */ STDMETHOD(QueryInterface) (THIS_ REFIID riid, void** ppvObj) PURE; STDMETHOD_(ULONG32,AddRef) (THIS) PURE; STDMETHOD_(ULONG32,Release) (THIS) PURE; /************************************************************************ * Method: * IRTALogSystem::Shutdown * Purpose: * Properly shuts down the log system. * Parameters: * None. * Returns: * PNR_OK - If success. * PNR_FAIL - Log system could not shutdown properly. * Notes: * Under Windows, this method should not be called from within DllMain(). */ STDMETHOD(Shutdown) (THIS) PURE; /************************************************************************ * Method: * IRTALogSystem::SetTranslationFileDirectory * Purpose: * Sets the translation file directory for the log system. * Parameters: * szTranslationFileDir - [in] Location of all log system translation files. These * files will be used to translate message numbers into text strings. * Returns: * PNR_OK - If success. * PNR_FAIL - Translation file directory already set. */ STDMETHOD(SetTranslationFileDirectory) (THIS_ const char* szTranslationFileDir) PURE; /************************************************************************ * Method: * IRTALogSystem::GetWriterInterface * Purpose: * Retrieves an interface to the log writer, used to send messages * into the log system. * Parameters: * ppIWriter - [out] Address of output variable that receives * the log writer interface pointer. * Returns: * PNR_OK - If success. * PNR_FAIL - Log system not properly initialized. */ STDMETHOD(GetWriterInterface) (THIS_ IRTALogWriter** /*OUT*/ ppIWriter) PURE; /************************************************************************ * Method: * IRTALogSystem::GetObserverManagerInterface * Purpose: * Retrieves an interface to the observer manager, used to subscribe, * manage, and unsubscribe listening observer which receive log messages. * Parameters: * ppILogObserverManager - [out] Address of output variable that receives * the observer manager interface pointer. * Returns: * PNR_OK - If success. * PNR_FAIL - Log system not properly initialized. */ STDMETHOD(GetObserverManagerInterface)(THIS_ IRTALogObserverManager** /*OUT*/ ppILogObserverManager) PURE; /************************************************************************ * Method: * IRTALogSystem::GetFunctionalAreaEnumerator * Purpose: * Retrieves an interface to an enumerator which will enumerate through * all functional areas in all namespaces in the specified language * loaded on log system initialization. * Parameters: * pIEnum - [out] Address of output variable that receives * the enumerator interface pointer. * szLanguage - [in] The language of the functional areas to be enumerated. * Returns: * PNR_OK - If success. * PNR_FAIL - Log system not properly initialized. */ STDMETHOD(GetFunctionalAreaEnumerator) ( IRTAFuncAreaEnum** /*OUT*/ pIEnum, const char* /*IN*/ szLanguage) PURE; }; /**************************************************************************** * Function: * RMAGetLogSystemInterface * Purpose: * Obtains an interface pointer to the log system. If the log system has not * yet been created, it is created and initialized. */ typedef PN_RESULT (STDAPICALLTYPE *FPRMAGETLOGSYSTEMINTERFACE)(IRTALogSystem** ppLogSystem); #endif