Global data

dbgeng.ANY_ID

Used with functions that take an id number to let the engine choose the id.

dbgeng.hr

Table containing HRESULT codes, with string names as keys and their corresponding numeric values. Contains at least the following keys:

  • S_OK
  • S_FALSE
  • E_FAIL
  • E_INVALIDARG
  • E_NOINTERFACE
  • E_OUTOFMEMORY
  • E_UNEXPECTED
  • E_NOTIMPL
  • ERROR_ACCESS_DENIED : numeric value is the evaluation of HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)

The dbgeng COM API is painstakingly implemented as functions that return HRESULT values, using out parameters to return values that are not suited to a simple HRESULT. The Lua functions that wrap the COM functions try to return sensible Lua values when they can, but when the underlying COM function returns an HRESULT that is not considered a success value, they almost always fall back to returning three values:

  • nil
  • a string value matching one of the HRESULT keys above
  • the corresponding numeric HRESULT value

Those return values should make it easy to determine which specific HRESULT was returned by comparing the strings directly or by comparing with the value of that key in the table.

For example, when calling dbgeng.symbolgroup.expand_symbol(), if the symbol cannot be expanded because it is already at the maximum expansion depth, the function will return nil, 'E_INVALIDARG', and the E_INVALIDARG numeric value. So complete error handling can be done as follows:

local expanded, hrstr, hrnum = sg:expand_symbol( index, true )
if expanded then
    -- success
elseif expanded == false then
    -- no children
elseif hrstr == 'E_INVALIDARG' then
    -- already at max expansion
elseif hrnum == dbgeng.hr.E_INVALIDARG then
    -- same as above elseif clause
elseif hrnum == dbgeng.hr.E_OUTOFMEMORY then
    -- memory allocation failed

    ... -- etc, more error handling
end

See HRESULT Values for common HRESULT return values and their usual meanings.

dbgeng.outctl

Table containing values that are used to control output. The values should be combined into a bitfield.

The lower bits of the bitfield must be exactly one of the following values:

  • THIS_CLIENT : Output generated by methods called by this client will be sent only to this client’s output callbacks.
  • ALL_CLIENTS : Output will be sent to all clients.
  • ALL_OTHER_CLIENTS : Output will be sent to all clients (except to the client that generated the output).
  • IGNORE : Output will be discarded immediately and will not be logged or sent to callbacks.
  • LOG_ONLY : Output will be logged but not sent to callbacks.

The higher bits of the bitfield may contain a combination of zero or more of the following values:

  • NOT_LOGGED : Do not put output from this client in the global log file.
  • OVERRIDE_MASK : Sends output to clients regardless of whether the client’s output mask allows it.
  • DML : For output that supports Debugger Markup Language (DML), sends the output in DML format.

As an alternative to creating a custom output control bitfield value, you can use one of the following values:

  • AMBIENT_DML : Sets the new output control to the same value as the current output control and specifies that the output will be in DML format.
  • AMBIENT_TEXT : Sets the new output control to the same value as the current output control and specifies that the output will be in text format.
  • AMBIENT : Same as AMBIENT_TEXT.

See DEBUG_OUTCTL_XXX.