This document describes how to embed Plugin Licensing in a TX plugin.

Requirements

A C++ TX plugin with source code. This plugin is used for integrating the plugin licensing. .NET is also supported.
ARES Commander 2019 SP0 or later (Windows only).

In this document, we name the new plugin SamplePlugin.

SDK

You can get the SDK from the OEM Portal. Alternatively, contact support@graebert.com.

The SDK includes the headers and libraries for the TX module and a sample.

Important Files and Folder Structure

The plugin licensing requires the following files to run in application as a plugin extension:

SamplePlugin.xml configuration file
SamplePlugin folder which contains all dependent modules for this plugin.

The base folder for all Plugins is the following:

X64 → c:\Program Files\Graebert GmbH\ARES Commander 20XX\Plugins
X86 → c:\Program Files (x86)\Graebert GmbH\ARES Commander 20XX\Plugins (x86 only supported until ARES Commander 2022 SP3.1)

SamplePlugin.xml

The configuration file SamplePlugin.xml is responsible for loading the correct module(s) of your plugin.

plugin_sample.xml has the following settings:

<?xml version="1.0" encoding="utf-8"?>
<plugin>
    <name>Plugin Sample</name>
    <version>1.0</version>
    <id>12345</id>
    <details>
        <api-level>2019</api-level>
        <modules>
            <module>plugin_sample/plugin_sample_4.03_15.tx</module>
            <module>%PROGRAMDATA%/new_plugin_sample_4.03_15.tx</module>
        </modules>
		<settings>
			<supportpath>C:\Program Files</supportpath>
			<supportpath>%TEMP%</supportpath>
			<supportpath>%FX_HOME_PATH%</supportpath>
			<supportpath>%APPDATA%</supportpath>
			<supportpath>%FX_APPDATA_PATH%</supportpath>
		</settings>
    </details>
</plugin>

Item	Description

Item	Description
name	The name of the plugin. You can use any name. Note: The name must match the SDK initialization name.
version	Any version of your plugin.
id	The unique identifier of the plugin. You can get the plugin ID from Graebert GmbH. The licensing process requires the plugin ID.
api-level	The API version of the core, which depends on the ARES Commander release version. For example, for ARES Commander 2019, api-level is 2019.
module	You can specify one or more modules that you want to load. If you do not specify the modules, the loader assumes it is a TX module. You can also load FRX, LISP modules and .NET assemblies when you add the parameter type="managed". Additionally, it is possible to load customization files such as MNU, MNI, MNS, CUIX, CUI, or XML.
supportpath	You can specify a support path ( which will be added to the ARES support paths ). Now the modules/files at this path can be accessed without specifying complete path again. Note: %-Windows Environment variables are available in latest releases of 2022 SP4 (21.4.1), and in 2023 SP2 (22.2.1) and all following versions.

SamplePlugin.xml also supports Windows Environment Variables like %HOME%, %TEMP% , %APPDATA% etc. and ARES specific Environment Variables like %FX_APPDATA_PATH% ,%FX_APPLICATION_PATH%, %FX_TEMP_PATH% etc., as can be seen in the SamplePlugin.xml above.

Plugin Licensing API

You can create a plugin that includes some free features as well as features that require a license. The plugin license must be checked in the plugin.
To check the license of the plugin in the plugin, do the following steps using Visual Studio.

Add the FxPL.lib library in the project properties under Linker > Input > Additional Dependencies.
Register the module. For example, you can register the module in the constructor of the TX module class:
CFxPluginInfo pluginInfo; pluginInfo._iLicenseID = 12345; // Get this number from Graebert GmbH. pluginInfo._sPluginName = CFxString::from_ansi_str( "Plugin Sample" ); // This must match the XML tag name. pluginInfo._iLicenseVersion = 8; // You will receive this number together with // the plugin ID from Graebert GmbH. //Set StandalonePlugin = true to Register Plugins having their own Licensing. pluginInfo._bStandalonePlugin = false ( By default = false ,plugins using Graebert Licensing ) // Registers the plugin in the system. GetFxLicensingAPI()->registerPlugin( pluginInfo ); // Triggers internet check for a valid license. GetFxLicensingAPI()->activate( true, 12345 );

( StandalonePlugins : Plugins which handle their own licensing and do not use Graebert Licensing )
These are all necessary steps to get it compiling and running with ARES Commander.

Plugin User Interface API

You can use Menu, Toolbar, and Ribbon API from the application. However, for plugins, we provide a simple solution to add items to the Ribbon. For example, you can add one or two buttons using the following API:

Add the FxPL.lib library to the project properties, under Linker > Input > Additional Dependencies.
Create a UserInterface item:
m_pUiItem = new CFxPluginUIItem(); m_pUiItem->_sId = CFxString::from_ansi_str( "ID_PLUGINS_SAMPLEPLG" ); // Use a unique ID to avoid problems with existing ID. m_pUiItem->_sName = CFxString::from_ansi_str( "Sample" ); // The name of the button. m_pUiItem->_sDescription = CFxString::from_ansi_str( "Runs the sample plugin." ); // The description when you hover the button (see status bar). m_pUiItem->_sCommand = CFxString::from_ansi_str( "_SAMPLEPLUGIN" ); // The command to execute. m_pUiItem->_sDarkIcon = CFxString(); // The icon used for the dark style. m_pUiItem->_sLightIcon = CFxString(); // The icon used for the light style.
Register and unregister the user interface using initApp and uninitApp: