Module entry points are special functions required for module installation and initialization. Entry points are called directly by the PixInsight core application and must be implemented following the standard 'C' naming and calling conventions as nonstatic, publicly visible global symbols.

In current versions of the PixInsight platform, there are two mandatory module entry points, namely the identification and initialization entry points (known as PMIDN and PMINI, respectively), and an optional (although usually necessary) installation entry point (PMINS). We describe these special functions in detail in this section.

PixInsight Module Identification (PMIDN) entry point

This function will be called by the PixInsight core application when it needs to retrieve identification and descriptive data from a module. This happens when a module is about to be installed, but also when a module is being inspected, either for security reasons or after a direct user request.

A PMIDN must have the following declaration:

PCL_MODULE_EXPORT uint32 IdentifyPixInsightModule( api_module_description** description, int32 phase );

pcl::int32

signed int int32

Definition: Defs.h:660

pcl::uint32

unsigned int uint32

Definition: Defs.h:666

Parameters

description Pointer to a pointer to an API module description structure. See the declaration of api_module_description in API/APIDefs.h for details. This structure must be provided by the called module as POD, and its starting address must be written to the pointer pointed to by this argument in a call to this function with phase = 1 (see below).

phase

Module identification request:

phase = 0x00 - Prepare for module identification.
phase = 0x01 - Report module descriptive data in a structure of type 'api_module_description', whose address must be stored in the pointer pointed to by the description argument.
phase = 0xff - Module identification process completed. The module description structure provided when phase = 1 can be deallocated and disposed as necessary.

Other values of phase may be passed in additional calls to a PMIDN. Those values and calls are reserved for special modules pertaining to the core of the PixInsight platform, and hence not in the user land. In current versions of PixInsight, such special calls must be ignored by the invoked module.

A PMIDN must return zero upon success. Any other return value will be interpreted as a module-specific error code.

Module developers using the standard PixInsight Class Library (PCL) distribution don't have to care about PMIDN, since it is already implemented internally by PCL.

Note: A PMIDN is mandatory for all PixInsight modules, and must be implemented as a nonstatic, publicly visible global symbol following the standard 'C' naming and calling conventions. The PCL_MODULE_EXPORT macro guarantees these conditions on all supported C++ compilers.

PixInsight Module Initialization (PMINI) entry point

This function will be called by the PixInsight core application when a module is being installed. It provides a module with the necessary elements to perform a bidirectional communication with the core application via the standard PCL API callback system.

A PMINI must have the following declaration:

PCL_MODULE_EXPORT uint32 InitializePixInsightModule( api_handle hModule, function_resolver R, uint32 apiVersion, void* reserved );

Parameters

hModule	Handle to the module being installed. This handle uniquely identifies the module, and must be used in all subsequent API calls requiring a module handle.
R	Pointer to an API function resolver callback. See the declaration of function_resolver in API/APIDefs.h and the automatically generated file pcl/APIInterface.cpp for details.
apiVersion	API version number.
reserved	Reserved for special invocations to core platform modules. Must not be used or altered in any way.

A PMINI must return zero upon success. Any other return value will be interpreted as a module-specific error code.

Module developers using the standard PixInsight Class Library (PCL) distribution don't have to care about PMINI, since it is already implemented internally by PCL.

Note: A PMINI is mandatory for all PixInsight modules, and must be implemented as a nonstatic, publicly visible global symbol following the standard 'C' naming and calling conventions. The PCL_MODULE_EXPORT macro guarantees these conditions on all supported C++ compilers.

PixInsight Module Installation (PMINS) entry point

If this function is defined as a public symbol in a module, the PixInsight core application will call it just after loading and initializing the module shared object or dynamic-link library. This happens after calling the mandatory module entry points PMIDN and PMINI.

A PMINS must have the following declaration:

PCL_MODULE_EXPORT int32 InstallPixInsightModule( int32 mode );

Parameters

mode	Specifies the kind of installation being performed by the PixInsight core application. See the pcl::InstallMode namespace for more information.

A PMINS must return zero upon successful installation. Any other return value will be interpreted as a module-specific error code.

Although a PMINS is optional, it normally has to be defined by non-trivial modules in order to create and initialize the different objects and meta-objects required to implement their functionality, since most of these objects are dynamic in PCL. See the source code of the open-source standard modules for examples. Look for <module_name>Module.cpp files.

Note: If available, a PMINS must be implemented as a nonstatic, publicly visible global symbol following the standard 'C' naming and calling conventions. The PCL_MODULE_EXPORT macro guarantees these conditions on all supported C++ compilers.