NSLogger API

NSLogger API

This page documents the client side NSLogger API you can use in your application

Logger initialization (optional)

Logger* LoggerInit();

Initializes a new logger. This is optional, unless you need multiple separate loggers. The first initialized logger becomes the default logger (you can change this by using LoggerSetDefaultLogger()). If you don’t call LoggerInit / LoggerStart, the first call that tries to send a log will create a default logger for you.

void LoggerStart(Logger *logger);

Start the logging thread. From this point on, you can start using logging calls. Note that the LoggerInit()/LoggerStart() pair is optional in most cases (unless you need multiple loggers).

void LoggerStop(Logger *logger);

Stop logging and disconnect from desktop viewer, if connected. This also stops the logging thread, and frees the Logger* structure. When using only one logger (the common case), you don’t really need to stop the logger before the application exits.

Logger configuration (optional)

void LoggerSetOptions(Logger *logger,
                       BOOL logToConsole,
                       BOOL bufferLocallyUntilConnection,
                       BOOL browseBonjour,
                       BOOL browseOnlyLocalDomains);

Change options for a logger (shortcut: pass NULL for the logger parameter to set the default logger’s options):

• logToConsole currently redirects traces to console (like NSLog()) instead of sending them over the wire. Warning the meaning of this option will change soon, allowing dual output of traces both to console and to the desktop viewer. This option is initially set to *NO.
• bufferLocallyUntilConnection determines whether the Logger stores traces in memory until a viewer connection is acquired. Initially set to YES.
• browseBonjour enables or disables Bonjour browsing to find the desktop viewer. You can disable Bonjour browsing when you are using a direct TCP/IP connection to a specific host.
• browseOnlyLocalDomains is a Bonjour browsing option that determines whether NSLogger should only look for loggers on the device’s local Bonjour domain (local.) or look into all domains (i.e. MobileMe, etc). Default value is YES.

void LoggerSetDefaultLogger(Logger *aLogger);

Change the default logger, which is by default the first initialized logger.

Logger* LoggerGetDefaultLogger(Logger *aLogger);

Retrieve the default logger. If you only use one logger (the common case, it is convenient to not store the Logger instance returned by LoggerStart(), but instead at close time to call: `LoggerStop(LoggerGetDefaultLogger());`

void LoggerSetViewerHost(Logger *aLogger, CFStringRef host, UInt32 port);

Configure a logger (shortcut: pass NULL to configure the default logger) to connect to a specific host (hostname or IP address) and port. This can be handy when you want to remotely log traces, or when multiple developers are using NSLogger on the same network. Note that when defining a viewer host, connecting to the host will be tried prior to browsing the Bonjour network.

Logging calls that use the default Logger

void LogMessageCompat(NSString *format, ...);

Log a string to the default logger. This call is fully compatible with NSLog().

void LogMessage(NSString *domain, int level, NSString *format, ...);
void LogMessage_va(NSString *domain, int level, NSString *format, va_list args);

Log a string to the default logger. Specifies a domain (can be NULL) and a level, for advanced filtering (i.e. log important messages to level 0, more debug info to level 1, etc). The va variant takes a standard *va_list* for the format arguments.

void LogData(NSString *domain, int level, NSData *data);

Log a binary data block to the default logger. Bytes and ASCII-equivalent characters will be fully displayed in the viewer application.

void LogImageData(NSString *domain, int level, int width, int height, NSData *data);

Log an image to the default logger. You can provide the actual widht / height of the image, or use a different size to scale large images to a smaller representation in the viewer application. Data can be in any format supported by Cocoa, PNG is recommended.

void LogStartBlock(NSString *format, ...);

Don’t use this function, grouped logging is currently evolving

void LogEndEndBlock();

Don’t use this function, grouped logging is currently evolving

Logging calls that target a specific logger

All the functions above have a ..To() equivalent that allow targetting a specific logger, if you are using multiple loggers.

void LogMessageCompatTo(Logger *logger, NSString *format, ...);
void LogMessageTo(Logger *logger, NSString *domain, int level, NSString *format, ...);
void LogMessageTo_va(Logger *logger, NSString *domain, int level, NSString *format, va_list args);
void LogDataTo(Logger *logger, NSString *domain, int level, NSData *data);
void LogImageDataTo(Logger *logger, NSString *domain, int level, int width, int height, NSData *data);
void LogStartBlockTo(Logger *logger, NSString *format, ...);
void LogEndBlockTo(Logger *logger);