Mozilla/mozilla/xpcom/base/nsILoggingService.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/**
 * LOGGING SERVICE
 *
 * See notes at the top of nslog.h for C++ usage.
 */

////////////////////////////////////////////////////////////////////////////////

%{C++
#include "prprf.h"
#include "prinrval.h"
#include <stdio.h>
%}

#include "nsISupports.idl"

typedef unsigned long PRIntervalTime;

interface nsILog;

////////////////////////////////////////////////////////////////////////////////

[scriptable, uuid(28efb190-b114-11d3-93b6-00104ba0fd40)]
interface nsILogEventSink : nsISupports
{
    readonly attribute string destinationName;
    void print(in nsILog log, in string msg);
    void flush(in nsILog log);
};

[ptr] native FILE(FILE);

[uuid(ef373116-a9d7-4b94-a3ae-2bc4e10213b3)]
interface nsIFileLogEventSink : nsILogEventSink
{
    /**
     * @param filePath - a native path to a log file,
     *                   or if "1", stdout, 
     *                   or if "2", stderr.
     */
    void init(in string filePath);
    [noscript] void initFromFILE(in string name, in FILE filePtr);
};

%{C++
#define NS_FILELOGEVENTSINK_CID                  \
{ /* 0ebdebe0-b14a-11d3-93b6-00104ba0fd40 */         \
    0x0ebdebe0,                                      \
    0xb14a,                                          \
    0x11d3,                                          \
    {0x93, 0xb6, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40} \
}

#define NS_FILELOGEVENTSINK_CONTRACTID      "@mozilla.org/file-log-event-sink;1"
#define NS_FILELOGEVENTSINK_CLASSNAME       "File Log Event Sink"
%}

////////////////////////////////////////////////////////////////////////////////

[scriptable, uuid(399d2370-b114-11d3-93b6-00104ba0fd40)]
interface nsILoggingService : nsISupports
{
    nsILog getLog(in string name);
    attribute unsigned long defaultControlFlags;
    attribute nsILogEventSink defaultLogEventSink;
    void describeLogs(in nsILog output);
};

%{C++
#define NS_LOGGINGSERVICE_CID                        \
{ /* 4f290320-b11c-11d3-93b6-00104ba0fd40 */         \
    0x4f290320,                                      \
    0xb11c,                                          \
    0x11d3,                                          \
    {0x93, 0xb6, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40} \
}

#define NS_LOGGINGSERVICE_CONTRACTID    "@mozilla.org/logging-service;1"
#define NS_LOGGINGSERVICE_CLASSNAME     "Logging Service"
%}

////////////////////////////////////////////////////////////////////////////////

[scriptable, uuid(3cddf0a0-b114-11d3-93b6-00104ba0fd40)]
interface nsILog : nsISupports
{
    readonly attribute string name;

    ////////////////////////////////////////////////////////////////////////////
    // Printing Routines

    boolean enabled();
    void print(in wstring message);
    void flush();

    void increaseIndent();
    void decreaseIndent();
    readonly attribute unsigned long indentLevel;

    void describe(in nsILog outLog);

    ////////////////////////////////////////////////////////////////////////////
    // Control Routines

    const unsigned long DEFAULT_DISABLED        = 0 << 0;
    const unsigned long DEFAULT_ENABLED         = 1 << 1;
    const unsigned long PRINT_THREAD_ID         = 1 << 2;
    const unsigned long PRINT_LOG_NAME          = 1 << 3;

    attribute unsigned long controlFlags;

    attribute nsILogEventSink logEventSink;

    ////////////////////////////////////////////////////////////////////////////

    // What's this? Why is this sort of thing in an interface definition?
    // The reason is that testing whether a log is enabled from C++
    // programs must be efficient so as not to impact the execution
    // of time-critical operations, yet still allow for logging them
    // in order to detect problems. (We're basically forcing every
    // implementation to implement this part.)
%{C++
    public:
        inline PRBool Test() { return mControlFlags & DEFAULT_ENABLED; }
        NS_IMETHOD Printf(const char* format, ...) = 0;
        NS_IMETHOD Vprintf(const char* format, va_list args) = 0;
    protected:
        PRUint32 mControlFlags;
%}
};

////////////////////////////////////////////////////////////////////////////////