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 plugin_sample.

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:

• plugin_sample.xml configuration file

• plugin_sample 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)

Plugin_sample.xml

The configuration file plugin_sample.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>

plugin_sample.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 plugin_sample.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.

1. Add the FxPL.lib library in the project properties under Linker > Input > Additional Dependencies.

2. 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:

1. Add the FxPL.lib library to the project properties, under Linker > Input > Additional Dependencies.

2. 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.

3. Register and unregister the user interface using initApp and uninitApp:

   void CFxSamplePluginModule::initApp()
   {
       if (GetFxLicensingUI()) 
           GetFxLicensingUI()->addUserInterface( m_pUiItem );
   } 
   
   void CFxSamplePluginModule::uninitApp() 
   { 
       if (GetFxLicensingUI()) 
           GetFxLicensingUI()->removeUserInterface(m_pUiItem); 
   }