EXT_COMMAND macro (engextcpp.hpp)

Article
04/01/2021

The EXT_COMMAND macro is used to define an extension command that was declared by using the EXT_COMMAND_METHOD macro.

An extension command is defined as follows:

Syntax

void EXT_COMMAND(
   _Name,
   _Desc,
   _Args
);

Parameters

_Name

The name of the extension command. This must be the same as the _Name parameter that is used to declare the extension command by using EXT_COMMAND_METHOD.

Because EXT_COMMAND is a macro, _Name must be the bare name of the extension command and should not be enclosed in quotation marks or be a variable.

_Desc

A string describing the extension command.

_Args

A string describing the arguments that are expected by the extension command. For information about how the _Args string is formatted, see Parsing Extension Arguments.

Note As an alternative to supplying a string that describes the arguments, you can use the string "{{custom}}" to indicate that the extension command will parse the arguments itself. The method GetRawArgStr can be used to fetch the raw argument for parsing.

Return value

None

Remarks

The body of the extension command does not take any arguments. However, because the extension command is declared as a method of the EXT_CLASS class, it has access to all the members of the ExtExtension base class, some of which are initialized for the execution of the extension command.

The macro EXT_COMMAND_METHOD should be used to declare the extension command. As with all C++ declarations, the EXT_COMMAND_METHOD declaration should appear in the source files before the EXT_COMMAND definition.

When the debugger engine calls an extension command method, it wraps the call in a try / except block. This protects the engine from some types of bugs in the extension code; but, since the extension calls are executed in the same thread as the engine, they can still cause it to crash.

This macro also creates a function called _Name (which calls the method defined by the macro). In order for the engine to call the extension, this function must be exported from the extension library DLL.

The EXT_CLASS constant specifies the name of the C++ class that represents the EngExtCpp extension library.

EXT_CLASS

    #ifndef EXT_CLASS
    #define EXT_CLASS Extension
    #endif

The default value of EXT_CLASS is Extension. You can change this value by defining EXT_CLASS before you include the header file Engextcpp.hpp.

Each extension command in the library is declared as a member of the class EXT_CLASS using the macro EXT_COMMAND_METHOD. For example, a library with two extension commands, extcmd and anotherextcmd, could define the class EXT_CLASS as follows:

class EXT_CLASS : public ExtExtension
{
public:
    EXT_COMMAND_METHOD(extcmd);
    EXT_COMMAND_METHOD(anotherextcmd);
}

Extension commands that have been declared by using EXT_COMMAND_METHOD should be defined by using EXT_COMMAND and should be exported from the library.

The EXT_DECLARE_GLOBALS macro creates a single instance of the EXT_CLASS class.

The EXT_DECLARE_GLOBALS macro sets up some global variables for use by the EngExtCpp extension framework. This include creating a single instance of the EXT_CLASS class that represents the EngExtCpp extension library.

One of the source files to be compiled into the EngExtCpp extension library should include the following command

EXT_DECLARE_GLOBALS()

Requirements

Requirement	Value
Target Platform	Desktop
Header	engextcpp.hpp (include Engextcpp.hpp)