/*

    File:       LogEngine.h

    Contains:   The core code to talk to the STREAMS log module.

    Written by: Quinn "The Eskimo!"

    Copyright:  © 1998 by Apple Computer, Inc., all rights reserved.

    Change History (most recent first):

    You may incorporate this sample code into your applications without

    restriction, though the sample code has been provided "AS IS" and the

    responsibility for its operation is 100% yours.  However, what you are

    not permitted to do is to redistribute the source as "DSC Sample Code"

    after having made changes. If you're going to re-distribute the source,

    we require that you make it clear in the source that the code was

    descended from Apple Sample Code, but that you've made changes.

*/

#pragma once

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

// Pick up low-level OT APIs.

#include <OpenTransportProtocol.h>

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

// Core Data Structure

enum {

    kMagicValue = 'Bing'

};

struct LogEntry {

    OTLink *fNext;

    OSType fMagic;              // Must be kMagicValue

    UInt32 fRefCount;

    UInt32 fTextLength;

    struct log_ctl fLogHeader;

    // variable length text goes here

};

typedef struct LogEntry LogEntry, *LogEntryPtr;

extern pascal void RetainLogEntry(LogEntryPtr thisEntry);

    // Increments the reference count for the log entry.

    // Clients can call this function to hold on to log

    // entries that are passed to them by ForEachNewLogEntry.

    //

    // Context: SystemTask /only/

extern pascal void ReleaseLogEntry(LogEntryPtr thisEntry);

    // Decrements the reference count for the log entry,

    // and frees the entry if count decrements to zero.

    // Clients should eventually call this function to free

    // any log entry they have retained.

    //

    // Context: SystemTask /only/

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

extern pascal OSStatus StartLogging(Boolean logErrors,

                                UInt32 traceInfoCount, struct trace_ids traceInfo[]);

    // Tells the module to start logging.  If logErrors is true,

    // the log will contain all strlog messages that have the

    // SL_ERROR bit in the flags when they are created.  If

    // traceInfoCount is non-zero, then we're also logging

    // traces.  traceInfo must point to an array of trace_ids

    // that describe which traces we're interested in.  Each

    // trace_id contains a field for module ID, for stream ID,

    // and for level.  Each field specifies the value of that

    // parameter we accept, or -1 to accept any value for that

    // parameter.  For example, the mid field is the module ID

    // whose traces we should accept, or -1 if you want to accept

    // traces for all modules.

    //

    // Context: SystemTask /only/

extern pascal void StopLogging(void);

    // Stops the logging process.  Call this if and only if

    // StartLogging returns noErr.  After stopping logging

    // you should call ForEachNewLogEntry to get any log

    // entries that might have accumulated in the time

    // between you making the StopLogging call and the time

    // that logging actually stops.

    //

    // Context: SystemTask /only/

extern pascal Boolean LoggingActive(void);

    // Returns whether logging is currently active.

    //

    // Context: SystemTask /only/

extern pascal UInt32 NumberOfDroppedLogEntries(void);

    // Returns the number of log entries that have been

    // dropped due to memory constaints.  This should

    // always be zero.

    //

    // Context: SystemTask /only/

typedef pascal void (*ProcessLogEntryProcPtr)(LogEntryPtr logEntry, void *refCon);

extern pascal void ForEachNewLogEntry(ProcessLogEntryProcPtr doThis, void *refCon);

    // This routine calls the supplied doThis routine for each

    // log entry that has arrived since the last time you called

    // this routine.  The log entry is immediately released

    // after doThis returns, so you should call RetainLogEntry

    // if you keep a reference to it.

    //

    // Context: SystemTask /only/