NSLogger API

NSLogger API

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

Sending logs (using the default logger)

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

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

void LogMessage(NSString *tag, int level, NSString *format, ...);
void LogMessageF(const char *file, int line, const char *function, NSString *tag, int level, NSString *format, ...);
void LogMessage_va(NSString *tag, int level, NSString *format, va_list args);

Log a string to the default logger. Specifies a tag (can be nil) and a level, for advanced filtering (i.e. log important messages to level 0, more debug info to level 1, etc). The ..F variant can report the file, line and/or function name the log call was originally made from. Typically, you’ll use the standard __FILE__, __LINE__ and __PRETTY_FUNCTION__ compiler defines. The .._va variant takes a standard va_list for the format arguments.

void LogData(NSString *tag, int level, NSData *data);
void LogDataF(const char *file, int line, const char *function, NSString *tag, 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 *tag, int level, int width, int height, NSData *data);
void LogImageDataF(const char *file, int line, const char *function, NSString *tag, 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.

Sending logs using a specific logger (advanced)

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 *tag, int level, NSString *format, ...);
void LogMessageToF(Logger *logger, const char *file, int line, const char *function, NSString *tag, int level, NSString *format, ...);
void LogMessageTo_va(Logger *logger, NSString *tag, int level, NSString *format, va_list args);
void LogDataTo(Logger *logger, NSString *tag, int level, NSData *data);
void LogDataToF(Logger *logger, const char *file, int line, const char *function, NSString *tag, int level, NSData *data);
void LogImageDataTo(Logger *logger, NSString *tag, int level, int width, int height, NSData *data);
void LogImageDataToF(Logger *logger, const char *file, int line, const char *function, NSString *tag, int level, int width, int height, NSData *data);

Utility functions

void LoggerFlush(Logger *logger, BOOL waitForConnection);

Ensure all the logs have been transmitted to the viewer, or written off to the buffer file. Call this function if you know your app is going
to quit or crash (for example, as the result of a failed assertion). See Integrating NSLogger in your application for examples of an assert() macro
redefinition that does exactly this.

Logger configuration (optional)

enum {
  kLoggerOption_LogToConsole               = 0x01,
  kLoggerOption_BufferLogsUntilConnection  = 0x02,
  kLoggerOption_BrowseBonjour              = 0x04,
  kLoggerOption_BrowseOnlyLocalDomain      = 0x08,
  kLoggerOption_UseSSL                     = 0x10
};

void LoggerSetOptions(Logger *logger, uint32_t flags);

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

• kLoggerOption_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 *0.
• kLoggerOption_BufferLogsUntilConnection determines whether the Logger stores traces in memory until a viewer connection is acquired. Initially set to 1.
• kLoggerOption_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. Initially set to 1.
• kLoggerOption_BrowseOnlyLocalDomain 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). Initially set to 1.
• kLoggerOption_UseSSL enables SSL connections to the viewer. Note that when connecting to a host using direct TCP/IP, you should always turn this flag on, as the desktop viewer makes SSL mandatory for remote connections.

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.

void LoggerSetupBonjour(Logger *aLogger, CFStringRef bonjourServiceName);

Refines the Bonjour configuration. Very useful in teamwork situations: on the viewer side, give a specific name to your Mac’s NSLogger (in the Preferences). On the client, specify the same name as the bonjourServiceName. When the clients looks over Bonjour for a viewer to connect to, it will connect only to the one you specified, instead of taking the first available. This way, multiple viewers and client can be live on your network, and each developer will receive traces only from the application they are working on.

void LoggerSetBufferFile(Logger *logger, CFStringRef absolutePath);

Configure NSLogger to write logs to a buffer file if no connection is acquired, instead of buffering logs in memory. You can set a buffer file at any point in time. All logs currently buffered in memory will be offloaded to the file. If a connection is acquired, the contents of the buffer file will be transmitted to the viewer, then the file will be emptied.

You can switch between file buffering and in-memory buffering at any time. You can also switch buffer files if you want to manage rolling log buffers.

Logger initialization (optional, only useful if you use multiple loggers simultaneously)

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.