pjs/xpcom/base/nsILoggingService.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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 Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

/**
 * 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);

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;
%}
};

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