/*++ EZDEF.H Copyright (C) 1999 Microsoft Corporation, all rights reserved. DESCRIPTION: ezlog unicode/ansi neuter definitions. NOTE: this file has no multi-include protection, because it is intended to be included multiple times WITHIN ezlog.h. Do not include this file directly. Created, Sep 3, 1999 by DavidCHR. --*/ typedef struct { ULONG MaskId; LPEZSTR LevelName; ULONG Precedence; ULONG Flags; } EZU(EZLOG_LEVEL_INIT_DATA), *EZU(PEZLOG_LEVEL_INIT_DATA); #ifndef EZLOG_OPENLOG_DATA_VERSION #define EZLOG_OPENLOG_DATA_VERSION 5 #endif #ifndef EZLOG_OPENLOG_DATA_REVISION #define EZLOG_OPENLOG_DATA_REVISION 1 #endif /* revision 1 ************************************************************ We use "REVISION" not "VERSION" because we can ADD more fields to our heart's content, just incrementing the version. However, once we need to eliminate fields, the structure is no longer backwards compatible. With any luck, we'll never have to remove fields. *************************************************************/ typedef struct EZU(__ezlog_openlog_data_revision1) { // ---------------------- version 1 ------------------------ IN ULONG Version; IN LPEZSTR LogFileName; IN OPTIONAL LPEZSTR BugFormatString; IN ULONG cLevels; IN EZU(PEZLOG_LEVEL_INIT_DATA) pLevels; IN ULONG Flags; // same as ezOpenLog flags. IN OUT PHANDLE phLog; /* if you want a log handle back, specify this here. */ // ------------------ end of version 1 -------------------- #if EZLOG_OPENLOG_DATA_VERSION >= 2 // ---------------------- version 2 ------------------------ IN LONG cReportBlockThresh; /* cReportBlockThresh tells ezCloseLog whether to report a full-blown statistics table. Basically, the report table is only generated if there are fewer than this number of blocks generated by the test. Specials include the following: */ #ifndef EZLOG_REPORT_ALL_BLOCKS # define EZLOG_REPORT_ALL_BLOCKS 0 /* this is the default-- all blocks are reported. This is what you get if you specify version 1. */ # define EZLOG_REPORT_NO_BLOCKS -1 /* don't ever report any block results. */ #endif #endif // ------------------ end of version 2 -------------------- #if EZLOG_OPENLOG_DATA_VERSION >= 3 // ------------------ version 3 --------------------------- OUT HANDLE hOutLog; /* This is set to the logging handle value (which is created regardless of whether you actually want one back). This is added for VB callers who apparently can't pass in a pointer to the handle to receive it, and might be more convenient for some callers regardless. */ IN LONG cReportBlockWidthThresh; /* cReportBlockWidthThresh is identical to cReportBlockThresh (above), except that it applies to the width. If the block table would be more than this wide, we don't show it at all. If you want to use this, a good value for it is 80. */ PEZLOG_FAILURE_CALLBACK_FUNCTION pFailureCallback; #endif // ------------------ end of version 3 -------------------- #if EZLOG_OPENLOG_DATA_VERSION >= 4 // ------------------ version 4 --------------------------- /* These control whether, which, and how often ezlog calls a list of user-supplied callback functions to receive the report information. This can also be done by specifying a list of DLLs per "resdll.h". */ IN OPTIONAL ULONG cPeriodicCallbacks; IN OPTIONAL PEZLOG_REPORT_FUNCTION *pPeriodicCallbacks; IN OPTIONAL DWORD msCallbackPeriod; // in milliseconds /* These control whether and which callbacks are invoked when the log is terminated. This can also be done by specifying a list of DLLs per "resdll.h". */ IN OPTIONAL ULONG cExitCallbacks; IN OPTIONAL PEZLOG_REPORT_FUNCTION *ppExitCallbacks; // ------------------ end of version 4 -------------------- #endif #if EZLOG_OPENLOG_DATA_VERSION >= 5 // ------------------ version 5 --------------------------- IN OPTIONAL LPTSTR BlockStartText; // default: "STARTING" IN OPTIONAL LPTSTR BlockFinishText;// default: "FINISHED" /* these specify a hint regarding the average precision for a filename or line number. If you specify a file length less than that of your BlockStartText or BlockFinishText, the hint will be increased to that length. If the given hint is less than the actual string length of the given string (file or stringized line), we INCREASE the hint for subsequent calls, so that filenames/line numbers remain properly aligned in the logfile. This behavior obviously does not extend to the below flags */ #ifndef EZLOG_DISABLE_FILE_AND_LINE #define EZLOG_DISABLE_FILE_AND_LINE ((LONG)(-1)) /* Don't print either value. Effective if either hint is set to this. */ #endif // EZLOG_DISABLE_FILE_AND_LINE IN LONG FileLengthHint; IN LONG LineLengthHint; // ------------------ end of version 5 -------------------- #endif } EZU(EZLOG_OPENLOG_DATA_REVISION1), *EZU(PEZLOG_OPENLOG_DATA_REVISION1); typedef EZU(EZLOG_OPENLOG_DATA_REVISION1) EZU(EZLOG_OPENLOG_DATA), *EZU(PEZLOG_OPENLOG_DATA); /* ezOpenLogEx{A|W} is fairly identical to ezOpenLog (it performs all the same functions), but the interface is more modular so that callers who want to define their own levels, or are paranoid about type checking and don't like typeless parameters (like me) can have type checking and a less cumbersome level system. */ EZLOGAPI EZU(ezOpenLogEx)( IN OUT EZU(PEZLOG_OPENLOG_DATA) pData ); EZLOGAPI EZU(ezOpenLog)( IN LPEZSTR LogFileName, IN OPTIONAL ULONG Options, /* IN levels */ /* OUT PHANDLE phLog */ /* IN NTBUG_FMT_STRING */ ... ); EZLOGAPI EZU(ezStartBlock)( IN OPTIONAL HANDLE hParent, /* Must be specified as NULL (default) or a blockid */ OUT OPTIONAL PHANDLE phBlockId, IN OPTIONAL ULONG flags , IN OPTIONAL ULONG defOutcome, /* the default outcome, if defOutcome is zero, will be set to the most innocuous level. */ IN LPEZSTR fmtForBlockName, ... ); #ifdef _VA_LIST_DEFINED /* va_list pointers must be passed in-- va_list may/may not be a structure depending on your architecture and/or compiler. I realize that C specs make it valid to pass, but it still generates a compiler warning. If you don't need the va_list, pass in NULL-- the functions will do the right thing. Get these functions by including */ typedef BOOL __cdecl EZU(VEZLOGMSG_FN)( IN ULONG, // level maskid IN OPTIONAL HANDLE, // hBlock/hLog IN LPEZSTR, // __FILE__ IN ULONG, // __LINE__ IN LPEZSTR, // fmt IN va_list * ); // pva #else /* This function type still needs to be defined if you include "resdll.h", so we typedef it to VOID. This way, ezLog can use function pointers that reference vezLogMsg without having to worry about whether the coder who #included this file can understand them-- they'll just be PVOID values to that code. */ typedef VOID EZU(VEZLOGMSG_FN); #endif typedef EZU(VEZLOGMSG_FN) *EZU(PVEZLOGMSG_FN); EXTERN_C EZU(VEZLOGMSG_FN) EZU(vezLogMsg); #if 0 EZU(vezLogMsg)( IN ULONG level, IN OPTIONAL HANDLE hBlockId, // or hLog-- either works. IN LPEZSTR file, // __FILE__ IN ULONG line, // __LINE__ IN LPEZSTR fmt, IN va_list *pva ); #endif typedef BOOL __cdecl EZU(EZLOGMSG_FN)( IN ULONG, // level maskid IN OPTIONAL HANDLE, // hBlock/hLog IN LPEZSTR, // __FILE__ IN ULONG, // __LINE__ IN LPEZSTR, // fmt ... ); typedef EZU(EZLOGMSG_FN) *EZU(PEZLOGMSG_FN); EXTERN_C EZU(EZLOGMSG_FN) EZU(ezLogMsg); #if 0 EZLOGAPI EZU(ezLogMsg)( IN ULONG level, /* EZLOG_PASS, etc. or a user-defined mask */ IN OPTIONAL HANDLE hBlockId, // or hLog IN LPEZSTR file, // __FILE__ IN ULONG line, // __LINE__ IN LPEZSTR fmt, ... ); #endif