nsIConsoleService

Implemented by: @mozilla.org/consoleservice;1 as a service:

var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                     .getService(Components.interfaces.nsIConsoleService);

Method overview

Methods

getMessageArray()

Get an array of all the messages logged so far.

void getMessageArray(
  [array, size_is(count)] out nsIConsoleMessage messages,
  out PRUint32 count
);

Parameters

messages

An array of current logged messages.

count

The number of messages in the array. If no messages are logged, this function will return a count of 0 but still will allocate one word for messages, so as to show up as a 0-length array when called from script.

void getMessageArray(
  [optional] out PRUint32 count,
  [retval, array, size_is(count)] out nsIConsoleMessage messages
);

Parameters

count

The number of messages in the array. If no messages are logged, this function will return a count of 0 but still will allocate one word for messages, so as to show up as a 0-length array when called from script.

logMessage()

void logMessage(
  in nsIConsoleMessage message
);

Parameters

message

An nsIConsoleMessage to log.

logStringMessage()

Convenience method for logging simple messages.

void logStringMessage(
  in wstring message
);

Parameters

message

The string to log.

registerListener()

Registers a listener for notification when an error is logged.

void registerListener(
  in nsIConsoleListener listener
);

Parameters

listener

The nsIConsoleListener to add.

reset()

Clear the message buffer (For example, for privacy reasons).

void reset();

Parameters

None.

unregisterListener()

Unregisters a listener.

void unregisterListener(
  in nsIConsoleListener listener
);

Parameters

listener

The nsIConsoleListener to remove.

Examples

Retrieving the message array

To retrieve the message array in Gecko prior to version 19:

function getConsoleMessageArray() {
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  var array = {};
  consoleService.getMessageArray(array, {});
  return array.value;
}

To retrieve the message array in Gecko 19 or later:

function getConsoleMessageArray() {
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  return consoleService.getMessageArray();
}

To retrieve the message array in a compatible way:

function getConsoleMessageArray() {
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  var array = {};
  return consoleService.getMessageArray(array, {}) || array.value;
}

Logging a simple message

A common usage is to log a string message to console:

function LOG(msg) {
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  consoleService.logStringMessage(msg);
}

Alternative logging methods include Components.utils.reportError and dump().

Logging a message with additional information

To include other information an nsIConsoleMessage object must be used. In this example nsIScriptError, which implements nsIConsoleMessage, is used to include information about the source file and line number of the error.

function myLogToConsole(aMessage, aSourceName, aSourceLine, aLineNumber, 
                        aColumnNumber, aFlags, aCategory)
{
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  var scriptError = Components.classes["@mozilla.org/scripterror;1"]
                              .createInstance(Components.interfaces.nsIScriptError);
  scriptError.init(aMessage, aSourceName, aSourceLine, aLineNumber, 
                   aColumnNumber, aFlags, aCategory);
  consoleService.logMessage(scriptError);
}

• aMessage — the string to be logged. You must provide this.
• aSourceName — the URL of file with error. This will be a hyperlink in the Error Console, so you'd better use real URL. You may pass null if it's not applicable.
• aSourceLine — the line #aLineNumber from aSourceName file. You are responsible for providing that line. You may pass null if you are lazy; that will prevent showing the source line in Error Console.
• aLineNumber and aColumnNumber — specify the exact location of error. aColumnNumber is used to draw the arrow pointing to the problem character.
• aFlags — one of flags declared in nsIScriptError. At the time of writing, possible values are:
  • nsIScriptError.errorFlag = 0
  • nsIScriptError.warningFlag = 1
  • nsIScriptError.exceptionFlag = 2 and
  • nsIScriptError.strictFlag = 4.
• aCategory — a string indicating what kind of code caused the message. There are quite a few category strings and they do not seem to be listed in a single place. Hopefully, they will all be listed in nsIScriptError.idl eventually.

See also

• Error Console (deprecated)
• Web Console
• Browser Console
• nsIConsoleMessage