[Artwork] / [QisMLib]

QisMLib Extensions

Gateway to the QisMLib system

C++ API for QisMLib extensions (qismextension.h)

class QisMExtensionAPI

Opaque interface to a QisMExtension API

class QisMExtensionAPI { ... };

Implementation_version()

Get any information specific to the API implementation

xxxxxxxxxx
virtual const char* Implementation_version() const = 0;

Extension_class_name()

Returns the name of the api class representing this extension (that directly inherits QisMExtensionAPI)

Extension_class_ptr()

Returns the ptr to the api class representing this extension (that directly inherits QisMExtensionAPI)

xxxxxxxxxx
virtual void* Extension_class_ptr() = 0;

Extension_class_ptr()

Returns the const ptr to the api class representing this extension (that directly inherits QisMExtensionAPI)

xxxxxxxxxx
virtual const void* Extension_class_ptr() const = 0;

class QisMExtensionReport

Pre-loaded extension API to enable dynamically loaded QisMExtensions to report information, warnings, errors during initialization so that they appear in the QisMExtension report obtained using QisMLib::Get_extension_report()

xxxxxxxxxx
class QisMExtensionReport: public QisMExtensionAPI { ... };

Report_info()

Report API specific information (version etc.)

• pre : Prefix to the message for formatting

• msg : Information string

• post : Suffix to the message for formatting

xxxxxxxxxx
virtual void Report_info(const char* pre, const char* msg, const char* post) = 0;

Report_warning()

Report any warnings encountered during initialization of a QisMExtension

• pre : Prefix to the message for formatting

• msg : Warning string

• post : Suffix to the message for formatting

xxxxxxxxxx
virtual void Report_warning(const char* pre, const char* msg, const char* post) = 0;

Report_error()

Report any errors encountered during initialization of a QisMExtension

• pre : Prefix to the message for formatting

• msg : Error string

• post : Suffix to the message for formatting

xxxxxxxxxx
virtual void Report_error(const char* pre, const char* msg, const char* post) = 0;

class QisMExtensionMgr

API to the component that manages QisMExtensions

xxxxxxxxxx
class QisMExtensionMgr { ... };

Register_extension_api()

Register an API with the extension manager so that it can be made available via QisMLib::Get_extension_api(...) for use in the client or other QisMExtensions

• apiName : A name string that uniquely identifies the API

• apiHandle : Component handle obtained via the QisMLib_extension_init_v2 call

• apiName MUST be a string literal, MUST have a unique address and MUST be persistant during the life of the program. It cannot be a string obtained from a temporary variable

• Duplicate apiName will be ignored

• The object that implements this API must persist as long as the component (shared library) is alive (in-between the QisMLib_extension_init_v2 and QisMLib_extension_close_v2 calls)

• A single component can register multiple extension APIs

xxxxxxxxxx
virtual void Register_extension_api(
  const char* apiName, QisMExtensionAPI* apiHandle
  ) = 0;

Get_qism_extension_api()

Get access to a pre-loaded extension API. Such an API is defined and implemented inside the QisM library and is guaranteed to be available during the initialization of the dynamic QisMExtensions (unlike QisMLib::Get_extension_api)

• apiName : A name string that uniquely identifies the API

• Success : A non-null handle to the API (needs to be dynamic_cast(ed) to the appropriate interface class)

• Failure : NULL. (API name was not found)

• This feature allows dynamic QisMExtension(s) to access functions that can aid their initialization during QisMLib_extension_init_v2

xxxxxxxxxx
virtual QisMExtensionAPI* Get_qism_extension_api(
  const char* apiName
  ) const = 0;

QisMLib_extension_init_v2() export

A function exported by a QisMExtension component (shared library) that gets called during QisMLib_initialize_once when that component is being loaded and allows the component to perform initialization of it's internal objects and resources as well as register one or more QisMExtension APIs

• modulePath : String containing path of the component (Do not store the pointer, make a copy of this string)

• handle : An opaque system handle that uniquely identifies the component (shared library) (output of LoadLibray/HMODULE on Windows, output of dlopen/void* on Linux)

• manager : Handle to the extension manager API (of type QisMExtensionMgr*)

• argC : No. of optional arguments passed to QisMLib_initialize_once

• argT : Array of arguments tags (argC count) passed to QisMLib_initialize_once

• argV : Array of argument values matching the corresponding argT (argC count) passed to QisMLib_initialize_once

• Return 0 if the intialization is successful. The corresponding component will be loaded and any registered APIs will be available as part of the QisM system

• non-zero if initialization failed. The corresponding component will be unloaded from the process

• This function is called by the QisMLib during QisMLib_initialize_once for each component listed in the qismlib.cfg file

• Only those components that define and export this function are treated as valid QisMExtensions and will be loaded

• Define this function in your extension component to do the following

  • Record the component path and handle for internal use

  • Initialize internal data structures and resources

  • Register extension APIs for use later

  • Provide meaninful information (version, warnings, error) to the extension report using QisMExtensionReport obtained via call to QisMExtensionMgr::Get_qism_extension_api

  • Allow the client to pass optional arguments to the component via argC, argT, argV

• This function is called by QisMLib once at the beginning for each component and should not be called by anyone else at any other time

xxxxxxxxxx
QISMEXTENSION_DECLSPEC int QisMLib_extension_init_v2(
  const char* modulePath, QisMExtensionHandle_t handle, 
  QisMExtensionMgr_p manager, const int argC, const char* const* argT, 
  void* const* argV
  );

QisMLib_extension_close_v2() export

A function exported by a QisMExtension component (shared library) that gets called at the end of the application when that component is being unloaded and allows the component to perform cleanup of it's internal objects and resources

• This function is called by the QisMLib at the end of the client application for each component listed in the qismlib.cfg file as it is being unloaded

• Define this function in your extension component to do the following

  • Cleanup internal data structures and release any resources

• This function is called by QisMLib once at the end for each component and should not be called by anyone else at any other time. The component may not be unloaded immediately by the system. However, for all practical reasons, the component must be considered as defunct at the end of this call

• This function may be called multiple times and therefore protect itself against double cleanup

xxxxxxxxxx
QISMEXTENSION_DECLSPEC void QisMLib_extension_close_v2();