madExcept Settings (runtime) 

www.madshi.net

Most madExcept settings can be configured at runtime, too. For that purpose there are a number of interfaces available. The settings are splitted into two main interfaces. The first one is named "IMESettings", the second one "IMEModuleSettings". The latter is a descendant of the first one. Why two interfaces instead of one? The reason is that you can adjust some settings on a per exception case, while others can only be adjusted globally. The exception interface IMEException is a descendent of the "IMESettings" interface. So all settings contained in the "IMESettings" interface can be adjusted locally for one specific exception. The settings which are only adjustable globally are contained in the "IMEModuleSettings" interface.

There are two different ways to change settings. First of all if an exception occurs, you can change settings for that exception simply by accessing the settings properties of the IMEException interface. The other way is to grab the "IMEModuleSettings" interface of a specific module (dll/exe/bpl). You can do that by using one of the overloaded "MESettings" functions.

type
  IMESettings       = interface               ['{27DBC590-890F-463E-8D05-32E33584119F}'];
  IMEModuleSettings = interface (IMESettings) ['{E2196B25-D73A-4F69-B79B-D65539763B31}'];

function MESettings                    : IMEModuleSettings; overload;
function MESettings (module : dword  ) : IMEModuleSettings; overload;
function MESettings (addr   : pointer) : IMEModuleSettings; overload;

function IMESettings.Module : dword;

function IMEModuleSettings.IsValid : boolean;
function IMEModuleSettings.Enabled : boolean;

// Example:
MESettings(GetModuleHandle('kernel32.dll')).IsValid -> false

Let's go through the settings properties in the same way the settings dialog is set up. The first tab contains the basic settings. These can't be adjusted at runtime through the settings interfaces. You can control the freeze check behaviour by using some global madExcept functions, though. E.g. have a look at PauseFreezeCheck, SetFreezeTimeout and ImNotFrozen.

// BASIC SETTINGS

// general options
function IMEModuleSettings.LinkInSettings  : boolean;  // link in madExcept settings
function IMEModuleSettings.LinkInMapFile   : boolean;  // link in function names and line numbers

// runtime checks
function IMEModuleSettings.CheckFileCrc    : boolean;  // check whether binary file is corrupt (via crc)
function IMEModuleSettings.CheckForFreeze  : boolean;  // check for frozen main thread
function IMEModuleSettings.FreezeTimeout   : dword;    // freeze timeout (sec)

// windows logo program
property IMEModuleSettings.WindowsLogo     : boolean;  // conform to "windows logo" requirements

// active error search
function IMEModuleSettings.ReportLeaks     : boolean;  // report resource leaks
function IMEModuleSettings.CrashOnOverrun  : boolean;  // instantly crash on buffer overrun
function IMEModuleSettings.CrashOnUnderrun : boolean;  // instantly crash on buffer underrun

Let's continue with the second tab of the settings dialog:

// ON EXCEPTION AUTO ACTIONS

// various actions
property IMESettings.AutoSave          : boolean;  // automatically save bug report
property IMESettings.AutoSaveIfNotSent : boolean;  // only if bug report doesn't get sent
property IMESettings.AutoSend          : boolean;  // automatically send bug report
property IMESettings.AutoSendPrgrBox   : boolean;  // show progress box during auto send
property IMESettings.AutoClipboard     : boolean;  // copy bug report to clipboard
property IMESettings.SuspendThreads    : boolean;  // pause all running delphi/bcb threads

// if madExcept is busy while no window is visible
property IMESettings.ShowPleaseWaitBox : boolean;  // show "please wait" box

// application control
// 0 = off; 1 = at once; xxx = after 10 crashes in xxx seconds
property IMESettings.AutoContinue      : boolean;  // automatically continue application
property IMESettings.AutoRestart       : dword;    // automatically restart application
property IMESettings.AutoClose         : dword;    // automatically close application

// runtime only settings
property IMESettings.AutoDelay         : dword;    // progress delay (in seconds)

Now let's have a look at the third tab of the settings dialog. The settings on this tab are only adjustable globally.

// EXCEPTION FILTER

// classes
property IMEModuleSettings.Filter1Classes : string;
property IMEModuleSettings.Filter2Classes : string;

// don't create a bug report
property IMEModuleSettings.Filter1NoBugReport : boolean;
property IMEModuleSettings.Filter2NoBugReport : boolean;
property IMEModuleSettings.GeneralNoBugReport : boolean;
// don't create a screen shot
property IMEModuleSettings.Filter1NoScreenShot : boolean;
property IMEModuleSettings.Filter2NoScreenShot : boolean;
property IMEModuleSettings.GeneralNoScreenShot : boolean;
// don't pause the running threads
property IMEModuleSettings.Filter1NoSuspend : boolean;
property IMEModuleSettings.Filter2NoSuspend : boolean;
property IMEModuleSettings.GeneralNoSuspend : boolean;
// don't call the exception handlers
property IMEModuleSettings.Filter1NoHandlers : boolean;
property IMEModuleSettings.Filter2NoHandlers : boolean;
property IMEModuleSettings.GeneralNoHandlers : boolean;

type
  TMEShowSetting = (ssFullBox, ssAssistant, ssDetailBox, ssSimpleBox, ssNothing);

// show setting
property IMEModuleSettings.Filter1ShowSetting : TMEShowSetting;
property IMEModuleSettings.Filter2ShowSetting : TMEShowSetting;
property IMEModuleSettings.GeneralShowSetting : TMEShowSetting;
// assistant
property IMEModuleSettings.Filter1Assistant : string;
property IMEModuleSettings.Filter2Assistant : string;
property IMEModuleSettings.GeneralAssistant : string;

Next we have the forth tab of the settings dialog.

// EXCEPTION BOX SETTINGS

// button configuration - visibility
property IMESettings.SendBtnVisible     : boolean;
property IMESettings.SaveBtnVisible     : boolean;
property IMESettings.PrintBtnVisible    : boolean;
property IMESettings.ShowBtnVisible     : boolean;
property IMESettings.ContinueBtnVisible : boolean;
property IMESettings.RestartBtnVisible  : boolean;
property IMESettings.CloseBtnVisible    : boolean;

type
  TMEButton = (bSendBugReport, bSaveBugReport, bPrintBugReport, bShowBugReport,
               bContinueApplication, bRestartApplication, bCloseApplication);

// button configuration - other options
property IMESettings.FocusedButton      : TMEButton;  // button focus
property IMESettings.SendAssistant      : string;     // send assistant
property IMESettings.SaveAssistant      : string;     // save assistant
property IMESettings.PrintAssistant     : string;     // print assistant

// various options
property IMESettings.AutoShowBugReport  : boolean;    // automatically show bug report
property IMESettings.NoOwnerDrawButtons : boolean;    // show standard buttons instead of fading owner draw buttons

Here comes the fifth tab:

// EMAIL & UPLOAD SETTINGS

// basic send settings
property IMESettings.SendInBackground     : boolean;    // send bug report in background
property IMESettings.MailAddr             : string;     // mail receiver(s)

// upload to web server
property IMESettings.UploadToFogBugz      : boolean;    // create FogBogz bug report
property IMESettings.UploadToBugZilla     : boolean;    // create BugZilla bug report
property IMESettings.UploadToMantis       : boolean;    // create Mantis bug report
property IMESettings.UploadToCustomScript : boolean;    // upload to HTTP custom script
property IMESettings.HttpServer           : string;     // FogBugz/BugZilla/Mantis/script url
property IMESettings.HttpSsl              : boolean;    // use SSL connection
property IMESettings.HttpPort             : dword;      // connection port
property IMESettings.HttpAccount          : string;     // http auth user name (optional)
property IMESettings.HttpPassword         : string;     // http auth password  (optional)
property IMESettings.BugTrackerAccount    : string;     // FogBugz/BugZilla/Mantis account
property IMESettings.BugTrackerPassword   : string;     // FogBugz/BugZilla/Mantis password
property IMESettings.BugTrackerProject    : string;     // FogBugz/BugZilla/Mantis project name
property IMESettings.BugTrackerArea       : string;     // FogBugz/BugZilla/Mantis area name
property IMESettings.BugTrackerAssignTo   : string;     // FogBugz/BugZilla/Mantis assign to

// send via SMTP
property IMESettings.MailAsSmtpServer     : boolean;    // act as SMTP server
property IMESettings.MailAsSmtpClient     : boolean;    // act as SMTP client
property IMESettings.SmtpServer           : string;     // SMTP server url
property IMESettings.SmtpSsl              : boolean;    // use SSL connection
property IMESettings.SmtpTls              : boolean;    // use TLS connection
property IMESettings.SmtpPort             : dword;      // connection port
property IMESettings.SmtpAccount          : string;     // SMTP account
property IMESettings.SmtpPassword         : string;     // SMTP password

// use local mail client
property IMESettings.MailViaMapi          : boolean;    // try to contact the mail client via MAPI
property IMESettings.MailViaMailto        : boolean;    // try to contact the mail client via mailto

// runtime only settings
property IMESettings.MailFrom             : string;     // SMTP mail sender
property IMESettings.AdditionalFields     : IMEFields;  // additional fields for http uploads

On to the sixth tab:

// ATTACHMENTS SETTINGS

// bug report & screen shot attachments
property IMESettings.AttachBugReport       : boolean;  // attach bug report
property IMESettings.AttachBugReportFile   : boolean;  // attach bug report file
property IMESettings.DeleteBugReportFile   : boolean;  // empty bug report file afterwards

// file names & zip configuration
property IMESettings.BugReportSendAs       : string;   // bug report send as
property IMESettings.BugReportZip          : string;   // bug report zip
property IMESettings.ScreenShotDepth       : integer;  // 0=none; 4=16 grays; 8=256 cols; x*1024=keep size < x KB
property IMESettings.ScreenShotAppOnly     : boolean;  // capture windows of the current application only
property IMESettings.ScreenShotSendAs      : string;   // screen shot send as
property IMESettings.ScreenShotZip         : string;   // screen shot zip
property IMESettings.AdditionalAttachments : IMEAttachments;

The next tab is the seventh:

// SAVE SETTINGS

// basic bug report file settings
property IMESettings.BugReportFile     : UnicodeString;  // bug report file
property IMESettings.AppendBugReports  : boolean;        // append bug reports
property IMESettings.BugReportFileSize : dword;          // bug report bug max file size (in bytes!)
property IMESettings.NoDupExcepts      : boolean;        // don't save duplicate exceptions
property IMESettings.NoDupFreezes      : boolean;        // don't save duplicate main thread freezings

type
  TMEDupDef = (ddExceptAddrIdentical, ddCrashStackIdentical, ddAllStacksIdentical);

// duplicate definitions
property IMESettings.DupExceptDef : TMEDupDef;  // "duplicate exceptions" definition
property IMESettings.DupFreezeDef : TMEDupDef;  // "duplicate main thread freezings" definition

Let's move on to the eighth tab:

// BUG REPORT SETTINGS

// what to you want to be contained in the bug report
property IMESettings.ListThreads       : boolean;  // callstack of all running threads
property IMESettings.ShowCpuRegisters  : boolean;  // cpu registers
property IMESettings.ShowStackDump     : boolean;  // stack dump
property IMESettings.ShowDisAsm        : boolean;  // exception location disassembly

// callstack options
property IMESettings.HideUglyItems     : boolean;  // hide callstack items which have no line number information
property IMESettings.ShowRelativeAddrs : boolean;  // show address offset to the beginning of the procedure
property IMESettings.ShowRelativeLines : boolean;  // show line number offset to the beginning of the procedure

// disassembly fine tuning
property IMESettings.FormatDisassembly : boolean;  // format disassembly output
property IMESettings.LimitDisassembly  : integer;  // limit number of asm instructions  (above & below exceptAddr)

// registered plugins
property IMESettings.PluginEnabled [plugin: string] : boolean;

// runtime only settings
function IMESettings.VersionVar        : string;   // contents of the version variable

The assistant creator tab is mainly about design time configuration. At runtime the only thing you can do is use the existing assistants.

// ASSISTANT CREATOR

// create an instance of the assistant with the specified name
function IMESettings.GetAssistant (name: string) : INVAssistant;

Last but not least we have the tenth tab:

// CUSTOM STRINGS

// except box
property IMESettings.TitleBar              : string;  // title bar
property IMESettings.ExceptMsg             : string;  // exception message
property IMESettings.FrozenMsg             : string;  // frozen message
property IMESettings.BitFaultMsg           : string;  // bit fault message

// except box - button captions
property IMESettings.SendBtnCaption        : string;
property IMESettings.SaveBtnCaption        : string;
property IMESettings.PrintBtnCaption       : string;
property IMESettings.ShowBtnCaption        : string;
property IMESettings.ContinueBtnCaption    : string;
property IMESettings.RestartBtnCaption     : string;
property IMESettings.CloseBtnCaption       : string;

// message box - button captions
property IMESettings.OkBtnCaption          : string;
property IMESettings.DetailsBtnCaption     : string;

// please wait box - strings
property IMESettings.PleaseWaitTitle       : string;
property IMESettings.PleaseWaitText        : string;

// send
property IMESettings.BugTrackerTitle       : string;  // bug tracker title
property IMESettings.BugTrackerDescription : string;  // bug tracker description
property IMESettings.MailSubject           : string;  // mail subject
property IMESettings.MailBody              : string;  // mail body
property IMESettings.SendBoxTitle          : string;  // send box title
property IMESettings.PrepareAttachMsg      : string;  // prepare attachments
property IMESettings.MxLookupMsg           : string;  // mx lookup
property IMESettings.ConnectMsg            : string;  // server connect
property IMESettings.SendMailMsg           : string;  // send mail
property IMESettings.FieldsMsg             : string;  // set http fields
property IMESettings.SendAttachMsg         : string;  // sending attachments
property IMESettings.SendFinalizeMsg       : string;  // finalization
property IMESettings.SendFailureMsg        : string;  // failure message

Sometimes when using 3rd party translation tools it makes sense to ask madExcept to reload its settings at a specific point in time. You can do so by calling the following method:

// reload the madExcept settings from the resource section
procedure IMEModuleSettings.Reload;

When sending emails and when uploading via HTTP you can add custom attachments, if you like. These attachments are managed through the "IMEAttachments" interface:

type
  IMEAttachments = interface ['{7DE1DA9C-28D7-4527-954F-F951B88BEE41}'];

// add an attachment
// originalFile   : full file path of the file which you want to attach
// sendAsFileName : under which name do you want the file to be sent
// zipFile        : do you want to zip the attachment? into which zip archive?
// fieldName      : under which field name shall the file be sent?
procedure IMEAttachments.Add (originalFile   : UnicodeString;
                              sendAsFileName : string = '';
                              zipFile        : string = '';
                              fieldName      : string = '');

// delete an attachment
function  IMEAttachments.Delete (originalFile: string) : boolean;
// delete all attachments
procedure IMEAttachments.Clear;

// enumerating attachments
property IMEAttachments.ItemCount : integer;
function IMEAttachments.GetItem (index              : integer;
                                 var originalFile   : UnicodeString;
                                 var sendAsFileName : string;
                                 var zipFile        : string;
                                 var fieldName      : string) : boolean;

// for thread safe handling you can lock and unlock the interface
procedure IMEAttachments.Lock;
procedure IMEAttachments.Unlock;

// cloning is used internally by madExcept, maybe you find it useful, too
function IMEAttachments.Clone : IMEAttachments;

// Examples:
MESettings.AdditionalAttachments.Add('c:\boot.ini');
exceptIntf.AdditionalAttachments.Add(ParamStr(0), '', 'crashingExe.zip');

When uploading a bug report via HTTP, you can add custom fields, if you want. These custom fields are managed through the "IMEFields" interface. The very same interface is also used for managing the bug report header and the bug report sections.

type
  IMEFields = interface ['{AF0EA7A7-2B36-46FD-BF2E-245ABA2740E2}'];

// add an item
procedure IMEFields.Add    (                item, content: string);
procedure IMEFields.Insert (index: integer; item, content: string);

// delete an item
procedure IMEFields.Delete (index: integer); overload;
procedure IMEFields.Delete (item : string ); overload;

// access to existing items
property IMEFields.ItemCount : integer;
property IMEFields.Items    [index : integer] : string;
property IMEFields.Contents [item  : string ] : string; default;
function IMEFields.FindItem (item  : string ) : integer;

// for thread safe handling you can lock and unlock the interface
procedure IMEFields.Lock;
procedure IMEFields.Unlock;

// cloning is used internally by madExcept, maybe you find it useful, too
function IMEFields.Clone : IMEFields;

// Examples:
MESettings.AdditionalFields['SomeField'] := 'SomeText';
exceptIntf.BugReportHeader['smiley'] := ':-)';