[Artwork] / [QisMLib]

QisMFlow

API to work with QisMLib flows (application logic)

• A flow is like a command-line application that is implemented inside QisMLib (in any of it's extensions) and usable as a C++ API

• An API provides granular ability to execute a very specific operation in memory via data structures and objects. A flow converts a set of command-line arguments to a pre-defined sequence of API calls to generate output (usually files on disk)

• A flow is an alternative way to write applications that can be used as a command-line EXE (with the help of qismflow64.exe) or an a function (like main)

QisMFlow C++ API (qismflow.h)

class QisMFlowUtil

class QisMFlowUtil { ... };

Represents the engine (application) that is executing a flow

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMFlowUtil_cast(const int version) = 0;
virtual const void* QisMFlowUtil_cast(const int version) const = 0;
virtual int QisMFlowUtil_latest_version() const = 0;

Exec_dir()

• Returns the location of qismlib64.dll/libqism64.so

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

Lib_handle()

• Returns the handle to QisMLib

xxxxxxxxxx
virtual QisMLib* Lib_handle() = 0;

Log_msg()

Log_str()

Send a message (or string) to the log (file/stdout)

• err is true if the message represents an error/warning (stderr)

• fmt is the format string (same as printf)

• str is a pre-formatted string

• New-lines are not added automatically. They MUST be added explicitly in the fmt or str

xxxxxxxxxx
virtual void Log_msg(const bool err, const char* fmt, ...) = 0;
virtual void Log_str(const bool err, const char* str) = 0;

Terminate_flow

Indicates that the flow needs to be terminated

• The flow implementation MUST periodically check this and if return != 0, gracefully return out of Run

• Return of 0 implies continue flow, !=0 implies terminate

xxxxxxxxxx
virtual int Terminate_flow() = 0;

class QisMFlow

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

• Represents a flow registered with QisMLib

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMFlow_cast(const int version) = 0;
virtual const void* QisMFlow_cast(const int version) const = 0;
virtual int QisMFlow_latest_version() const = 0;

Run()

Execute the flow

• util represents the engine that is executing this flow

• argc, argv are the list of command-line style parameters relevant to this flow

• Returns 0 on success. Otherwise use Get_error_* for information about the error with the return code

xxxxxxxxxx
virtual int Run(QisMFlowUtil* util, const int argc, const char* const* argv) = 0;

Get_error_msg()

Get_error_tag()

Get_error_context()

Get the error information corresponding to a condition represented by ecode

xxxxxxxxxx
virtual const char* Get_error_msg(const int ecode) const = 0;
virtual const char* Get_error_tag(const int ecode) const = 0;
virtual const char* Get_error_context(const int ecode) const = 0;

Get_usage()

Returns the flow usage as a multi-line string

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

Get_version()

Returns the flow name and version as a single string

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

class QisMFlowRegister

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

Represents the registry of QisMLib flows

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMFlowRegister_cast(const int version) = 0;
virtual const void* QisMFlowRegister_cast(const int version) const = 0;
virtual int QisMFlowRegister_latest_version() const = 0;

Register_flow()

Add a flow identified by name and implemented by handle to the registry of flows

xxxxxxxxxx
virtual void Register_flow(const char* name, QisMFlow* handle) = 0;

Get_flow()

Get the handle for the flow identified by name

xxxxxxxxxx
virtual QisMFlow* Get_flow(const char* name) = 0;

List_flows()

Get a list of available flows as a string of names seperated by sep

xxxxxxxxxx
virtual const char* List_flows(const char* sep = "; ") const = 0;