Plugin registration and initialisation

Overview

The code described in this section will be automatically generated by the Visual Studio template wizard for creating plugin projects.  A knowledge of the details is not required unless custom changes are necessary.

The following describes how the registration process works and how modifications may be made.

Registration

The first call into every plugin is to a registration function called tsc_RegisterPlugin.  This function must return two strings that describe the plugin.  No other processing should be done here.  Note that if this method is not defined correctly, the linker will fail with an "undefined symbol" error for the name tsc_RegisterPlugin.

The tsc_RegisterPlugin function should look similar to this:

extern void tsc_RegisterPlugin (const char*& pluginName,

                                const char*& optionalTdbRelativePath)

{

    pluginName  = "My survey app";

    optionalTdbRelativePath = "MyPlugin.tdb";

    tsc_SurveyCore::RegisterAssets (

    {

        {IDB_FolderIcon,  "FolderPic.png"},

        ...

    }); 

}

pluginName is a short name name by which the plugin is described in error dialog boxes, log messages and the like.

optionalTdbRelativePath is a path string to the tdb file that contains the language translations that the plugin is using.  It should be a path relative to the plugin DLL's directory.  It is optional to use a TDB; set it to an empty string if no TDB file is used.  If you specify a TDB file but it fails to load (eg, it doesn't exist or contains syntax errors) then the plugin will be unloaded.  A TDB file that is out of date with respect to the x_Codes compiled into the plugin may crash at runtime, or provide incorrect strings.  See the language translations page for more information.

Initialisation

When Survey Core starts, it will call the plugin's initialisation function.  This must be a parameterless function called tsc_InitializePlugin.  This function should be defined using extern so that Survey Core can call it.   Typically, this function is used to register the plugin as an application plus any other setup that is required, such as registering UITasks.

Do not attempt to call any other UI functions from within tsc_InitializePlugin, they are doomed to failure.

Since version 20.10, any resources required by the plugin must be registered in this function, by calling the tsc_SurveyCore::RegisterAssets() method and passing an initializer list with a mapping between resource numbers and filenames, in a similar manner to the Windows .rc file (which is replaced by this scheme). The resource numbers are arbitrary and can be defined in any manner valid in C++ as an integer greater then zero. It would be advisable to stick with a single method though.

// A variety of ways you can define resource IDs:
#define IDB_FolderIcon 567

constexpr int IDF_TemplateXml = 1;

enum {IDB_Pencil = 2, IDB_StartButton, IDB_StopButton, ...};

extern void tsc_InitializePlugin ()

{

    bool success = true;

    success &= tsc_SurveyCore::RegisterApplication (new MyApplication);

    success &= tsc_SurveyCore::RegisterUITask (...);

    tsc_SurveyCore::RegisterAssets (

    {

        {IDB_FolderIcon,  "FolderPic.png"},

        {IDB_Pencil,      "Pencil.png"},

        {IDF_TemplateXml, "CustomDataTemplate.xml"}

    });

     // Other initialization code here 

} 

Finalisation

When Survey Core is shutting down, a finalisation function is called in the plugin, where any tidying up can be performed, such as releasing resources.  Most API methods that require Survey Core services will be inoperative at this time.  If no finalisation code is required, an empty function must still be defined.

extern void tsc_FinalizePlugin ()

{

      // Finalization code here 

} 

Versioning

Your plugin should have a version information section in its scapi.props file (configurable using the Properties Manager in MSVC) which reports the version number.  All plugin properties can be found in the User Macros section of this file.

The version number is important; it affects how Trimble Access Installation Manager deals with installing your plugin on a user's device.  Supply at least three integers, and increment the version for any new release of the plugin.  A new plugin will only be installed on a user's device if the version number is greater than the currently installed version, or if the plugin is not installed.  Uninstalling a plugin can be used force a new install.