Appservice

Interfaces to handle app services and app instances.
Basically each App has one class which is derived from the base class AppService. This base class establishes a unix domain socket connection to the manager app, which controlls the creation, starting and stopping of instances.
Each instance itself is derived from AppInstance and gets its own AppInstanceArgs.

File information

Logging

Classes

class AppService : public UAppServiceSocket, public IInstanceLog {    
public:
    AppService(class IIoMux * const iomux, class ISocketProvider * const localSocketProvider, AppServiceArgs * serviceArgs);
    
    virtual class AppInstance * CreateInstance(AppInstanceArgs * args) = 0;
    virtual void AppServiceApps(istd::list * appList) = 0;
    virtual void AppInstancePlugins(istd::list * pluginList) {};

    void AppStart(AppInstanceArgs * args) override;
    void AppStopped(class AppInstance * instance);
    const char * GetAppServiceId() const;
    const char * GetAppPlatformDNSName() const;
    const char * GetAppPlatformTimeZoneString() const;
    void SetAllInstancesLogFlags(ulong64 logFlags);
};

Public functions

Constructor

Parameters

class IIoMux * const iomux	An IIoMux pointer to the IIoMux class.
ISocketProvider * const localSocketProvider	An ISocketProvider pointer to a local socket provider.
AppServiceArgs * serviceArgs	An AppServiceArgs pointer to the service arguments struct.

You must override this function inside your class which implements the AppService class.
This function creates an object of the instance class of the App which must be derived from the class AppInstance.
If this object is stopped and has finished stopping, it must call AppStopped, see below.

Parameters

AppInstanceArgs * args

An AppInstanceArgs pointer to the instance arguments.

Return value

The created AppInstance object.

You must override this function inside your class which implements the AppService class.
Push your provided apps to the appList. Each app has to be an instance of class AppServiceApp. An app of an AppService might be configured inside the PBX App object.

Parameters

istd::list<AppServiceApp> * appList

A list to add all AppServiceApps.

You can override this function inside your class which implements the AppService class if your app provides app instance plugins (PBX manager plugins).
Push your provided plugins to the pluginList. Each app has to be an instance of class AppInstancePlugin.
See publish manager plugins for further reference.

Parameters

istd::list<AppInstancePlugin> * pluginList

A list to add all AppInstancePlugins.

You can start an own app instance, e.g. inside your app-main.cpp, if you want to start an instance outside of the manager control.

Parameters

AppInstanceArgs * args

An AppInstanceArgs pointer to the instance arguments.

Call this function when your app stopped.

Parameters

AppInstance * instance

An AppInstance pointer to the instance object.

Return value

The service id of the app service.

Return value

The app platform DNS name which can be configured inside the manager settings.

Return value

The app platform timezone string which can be configured inside the manager settings.

Call this function if you want to set the logFlags of all instances to a certain value.

Parameters

ulong64 logFlags

The logFlags to set.

class AppInstance : public IInstanceLog {    
public:
    AppInstance(class AppService * appService, AppInstanceArgs * args)
    const char * GetAppServiceId() const;
    const char * GetAppName() const;
    const char * GetAppDomain() const;
    const char * GetKey() const;
    void SetLogFlags(ulong64 logFlags);
    static char * GenerateKey(const char * appName, const char * appDomain);
    void LogV(const char * format, va_list ap);
    void Log(const char * format, ...);
    void HexDump(const void * buffer, size_t size);
    void SetAlarm(word code, ServiceAlarmSeverity severity, char * text, char * details);
    void ClearAlarm(word code, ServiceAlarmSeverity severity, char * text, char * details);
    void SendEvent(word code, ServiceAlarmSeverity severity, char * text, char * details);
    virtual void Stop() = 0;
    virtual void ServerCertificateUpdate(const byte * cert, size_t certLen) {};
    virtual void SetAppDomain(const char * domain, const char * pwd) {};
};

Public functions

Constructor

Parameters

AppService * service	An AppService pointer to the app service class.
AppInstanceArgs * instanceArgs	An AppInstanceArgs pointer to the instance arguments struct.

Return value

The app service id.

Return value

The app name.

Return value

The app domain.

Return value

The unique key string which identifies the app instance: "appname@appdomain".

Call this function to set the logFlags of the instance.

Parameters

ulong64 logFlags

The logFlags to set.

Generates the unique string which identifies an intance.

Parameters

const char * appName	The app name.
const char * appDomain	The app domain.

Return value

The unique key string which identifies the app instance: "appname@appdomain". Must be freed by the caller!

Writes the log string to the debug output (e.g. file or debugging output).

Parameters

const char * format	The format string.
va_list ap	A variable argument list with all arguments which are used inside the format string.

Writes the log string to the debug output (e.g. file or debugging output).

Parameters

const char * format	The format string.
...	Further arguments used inside format string.

Writes a hexdump of the buffer to the debug output (e.g. file or debugging output).

Parameters

const void * buffer	The buffer.
size_t size	The size to dump.

Sets an alarm, which is sent to the manager (which again sends it to an alarm and events server). An alarm is active until it is cleared.

Parameters

word code	A code to identify an alarm.
ServiceAlarmSeverity severity	The severity.
char * text	The text which identifies the alarm.
char * details	Further details for the alarm.

Clears an alarm.

Parameters

See SetAlarm for parameter reference.

Sends an event.

Parameters

See SetAlarm for parameter reference.

You must override this function. It is called if the instance or service is stopped by the manager.
You must call AppService::AppStopped asynchronously if everything has been stopped.

You can override this function if you need to be notified about the webserver certificate. You can then pass the certificate to an ISocketContext.

Parameters

const byte * cert	The certificate byte buffer.
size_t certLen	The length of the byte buffer.

Shouldn't be used inside app code.

class AppServiceApp {    
public:
    AppServiceApp(const char * name, bool websocketOnly = false);
    const char * GetName();
    bool IsWebsocketOnly();
};

Public functions

Constructor

Parameters

const char * name	The name describes the last URL part of the app.
bool websocketOnly	An app which can be just used with a websocket connection.

Return value

The name.

Return value

The websocketOnly value.

class AppInstancePlugin {    
public:
    AppInstancePlugin(const char * plugin, const char * icon, const char * langFile, bool wildcard = false, const char * api = NULL);
    
    bool wildcard;

    const char * GetIcon();
    const char * GetApi();
    const char * GetPlugin();
    const char * GetLangFile();
};

Public functions

Data types

ServiceAlarmSeverity

typedef enum {
    ALARM_SEVERITY_INDETERMINATE,
    ALARM_SEVERITY_MAJOR,
    ALARM_SEVERITY_CRITICAL
} ServiceAlarmSeverity;

Overview

ServiceAlarmType

typedef enum {
    ALARM_TYPE_SET,
    ALARM_TYPE_CLEAR,
    ALARM_TYPE_ERROR
} ServiceAlarmType;

Overview

AppServiceArgs

struct AppServiceArgs {
    void Parse(int argc, char ** argv, bool keepDefaults = true);
    const char * serviceID;
    const char * manager;
    const char * appPlatformDNSName;
    ulong64 logFlags;
    bool segfaulted;
    bool disableHexdumps;
    off_t logFileSize;
};

Overview

Parameters

AppInstanceArgs

struct AppInstanceArgs {
    AppInstanceArgs();
    void Parse(int argc, char ** argv, bool keepDefaults = true);
    const char * appName;
    const char * appDomain;
    const char * appPassword;
    const char * webserver;
    const char * webserverPath;
    const char * dbHost;
    const char * dbName;
    const char * dbUser;
    const char * dbPassword;
    const char * workingPath;
    ulong64 logFlags;
};

Overview

Parameters

Code Example

class TestInstance : public AppInstance {
    ISocketContext * socketContext;
    ISocket * socket;
    void Stop() override;
    void ServerCertificateUpdate(const byte * cert, size_t certLen)  override;
    void TryStop();
public:
    TestInstance(class IIoMux * const iomux, class TestService * testService, class ISocketProvider * localSocketProvider, class IDatabaseProvider * databaseProvider, class IWebserverPluginProvider * webserverPluginProvider, AppInstanceArgs * instanceArgs);
    ~TestInstance();
};

class TestService : public AppService {
    class IIoMux * const iomux;
    class ISocketProvider * localSocketProvider;
    class ISocketProvider * tlsSocketProvider;
    class IDatabaseProvider * databaseProvider;
    class IWebserverPluginProvider * webserverPluginProvider;
public:
    TestService(class IIoMux * const iomux, class ISocketProvider * localSocketProvider, class ISocketProvider * tlsSocketProvider, class IDatabaseProvider * databaseProvider, class IWebserverPluginProvider * webserverPluginProvider, AppServiceArgs * serviceArgs);
    ~TestService();
    class AppInstance * CreateInstance(AppInstanceArgs * instanceArgs) override;
    void AppServiceApps(class json_io & json, word base) override;
};

TestService::TestService(class IIoMux * const iomux, class ISocketProvider * localSocketProvider, class ISocketProvider * tlsSocketProvider, class IDatabaseProvider * databaseProvider, class IWebserverPluginProvider * webserverPluginProvider,  AppServiceArgs * serviceArgs)
    : AppService(iomux, localSocketProvider, serviceArgs),
    iomux(iomux)
{
    this->databaseProvider = databaseProvider;
    this->localSocketProvider = localSocketProvider;
    this->tlsSocketProvider = tlsSocketProvider;
    this->webserverPluginProvider = webserverPluginProvider;
}

TestService::~TestService()
{
}

class AppInstance * TestService::CreateInstance(AppInstanceArgs * instanceArgs)
{
    return new class TestInstance(iomux, this, localSocketProvider, tlsSocketProvider, databaseProvider, webserverPluginProvider, instanceArgs);
}

void TestService::AppServiceApps(istd::list<AppServiceApp> * appList)
{
    appList->push_back(new AppServiceApp("devices"));
    appList->push_back(new AppServiceApp("sysclients", true));
}

TestInstance::TestInstance(class IIoMux * const iomux, class TestService * testService, class ISocketProvider * localSocketProvider, class ISocketProvider * tlsSocketProvider, class IDatabaseProvider * databaseProvider, class IWebserverPluginProvider * webserverPluginProvider, AppInstanceArgs * instanceArgs) :
AppInstance(testService, instanceArgs)
{
    this->iomux = iomux;
    this->databaseProvider = databaseProvider;
    this->webserverPlugin = webserverPluginProvider->CreateWebserverPlugin(iomux, localSocketProvider, this);
    this->socketContext = tlsSocketProvider->CreateSocketContext(this);
    this->socket = tlsSocketProvider->CreateSocket(iomux, NULL, this, false, socketContext);
    webserverPlugin->RegisterForPath(instanceArgs->webserver, instanceArgs->webserverPath);
    this->Log("TestInstance created");
}
TestInstance::~TestInstance()
{
    this->Log("TestInstance deleted");
}
void TestInstance::ServerCertificateUpdate(const byte * cert, size_t certLen)
{
    this->socketContext->SetServerCertificate(cert, certLen, NULL);
}
void TestInstance::Stop()
{
    TryStop();
}
void TestInstance::TryStop()
{
    // if everything has been closed, call AppStopped
    appService->AppStopped(this);
}