ServiceHost

class kanzi::connect::ServiceHost

Abstract base class that abstracts the origin of the service and simplifies the service management.

Services can be hosted locally in server or remotely in client. This class simplifies the server-side service management by abstracting the actual origin of the service. See LocalServiceHost and RemoteServiceHost for local and remote variants.

Subclassed by LocalServiceHost, RemoteServiceHost

Public Types

typedef function<void(ServiceHost*, RuntimeDataObjectSharedPtr)> ConfigurationPropertyChangedCallback

Callback prototype to invoke when service configuration properties change.

Public Functions

ServiceHost(ServiceRuntimeDataRegistrySharedPtr registry = ServiceRuntimeDataRegistrySharedPtr())

C++ constructor.

Parameters

  • registry: runtime data registry.

~ServiceHost()

Destructor.

AbstractSessionSharedPtr acquireSession(ConnectedClientSharedPtr client, int sessionId) = 0

Creates a session to this service.

Return

session instance. ownership not transfered.

Parameters

  • client: identifies the client.

  • sessionId: identifies the session.

void changeType(const string &type) = 0

Changes the interface name at runtime.

Parameters

  • type: new type for the interface.

int clientID() const = 0

Returns the client identifier.

Relevant only for remote clients. Will return -1 for local clients.

Return

client identifier.

int countSessions() const = 0

Returns amount of sessions towards this service.

Return

amount of sessions

void ensureDomain(ConnectDomain *domain)

Ensure that service instance (if local) has domain set.

If not set earlier will put the provided domain.

Parameters

  • domain: which domain to put the service in case not previously bind.

ClientDescriptorSharedPtr getClientDescriptor() = 0

Return the client descriptor.

Relevant only for remote services.

Return

client descriptor

RuntimeDataObjectSharedPtr getConfigurationProperties() = 0

Retrieve service configuration properties.

Return

properties as shared object.

const AbstractService::ServiceDescription &getDescription() = 0

Retrieve the service description from service host.

Return

const reference to service description

string getIdentifier() const = 0

Retrieve interface identifier.

Return

interface ID this service handles.

RuntimeDataObject *getRuntimeData()

Internal API for across service scripting, not for public use.

Request a pointer to service host runtime data. Returned data (if any) may be a mirror to a service registry so modifying values here may not be visible for the hosted service itself.

AbstractServiceSharedPtr getService() const = 0

Returns a service instance.

Relevant only for local services.

Return

service

const string getServiceDescriptionSchema(bool details = false)

Retrieve service description schema.

Return

xml format service description.

Parameters

  • details: if true more detailed description is provided. if false then only limited set of information that kanzi studio can handle is provided.

string getServiceRoutingInformationDescription(int serverclientid) = 0

Must be overridden by the corresponding implementation.

Return

xml format routing information for the service.

shared_ptr<ServiceServiceConcept::Session> getServiceSession() const = 0

Returns a session to remote service.

Relevant only for remote services.

Return

session

const AbstractService::ServiceState &getState() = 0

Retrieve the service state information.

Return

const reference to service state information.

void initialize(InterfaceDomainBase *domain, ContentClientSharedPtr contentClient, WorkQueueInterface *workQueue) = 0

Initialize the service.

Parameters

  • domain: environment where the service is run in.

  • contentClient: access to content system

  • workQueue: interface to work queue used to dispatch work service is ready will eventually cause the services work() method to be invoked.

bool local() const = 0

Is this service local or not.

Return

true if service is local

void notifyAll(const MessagePackage&)

Internal API for across service scripting, not for public use.

Notify all client sessions with message.

void notifyClientDisconnected(int clientId) = 0

Invoked to inform that specific client has disconnected.

Parameters

  • clientId: Identifies the client.

void receiveMessage(ConnectedClientSharedPtr client, const MessagePackage &message) = 0

Invoked for each message this service should handle.

Parameters

  • client: identifies the message sender

  • message: the message to process.

bool registerServiceRuntimeData(const string schema = "")

Invoked to register service runtime data.

Return

true if registered successfully.

Parameters

  • schema: the schema (xml)

bool registerServiceRuntimeDataSchemaChange(const string &xml)

Invoked to change runtime data schema at runtime.

Return

true on success.

Parameters

  • xml: the xml structure

void releaseSession(int clientId, int sessionId) = 0

Releases a session.

Parameters

  • clientId: identifies the client

  • sessionId: identifies the session

bool reportServiceRuntimeData(const string&, const string&)

Can be called, mainly for remote services, to inform about new service information that was received.

void setConfigurationProperties(RuntimeDataObjectSharedPtr)

Stores service configuration properties.

Default implementation is empty, should be overridden by the remote service host implementation

Parameters

  • properties: data object describing the properties.

void setConfigurationPropertyChangedCallback(ConfigurationPropertyChangedCallback callback)

Install a callback to be invoked when configuration property changes.

Parameters

  • callback: to be invoked.

void setState(const AbstractService::ServiceState &state) = 0

Sets the service state.

Relevant only for remote clients.

Parameters

  • state: new state for remote clients.

bool subscribeForRuntimeDataSchemaChanges(GenericSyncObserver<> &observer)

Start getting notifications of runtime data schema changes.

Return

True if subscription was successful, will not accept double subscription

Parameters

  • observer: The instance which will start receiving notifications

void uninitialize() = 0

cleanup the service.

bool unsubscribeForRuntimeDataSchemaChanges(GenericSyncObserver<> &observer)

Stop receiving notifications of runtime data schema changes.

Return

True if unsubscription was successful

Parameters

  • observer: The instance which will stop receiving notifications

void work(ConnectWorkItemSharedPtr workItem) = 0

Routine that get(s) called periodically or especially when object itself has requested it to be called using the work queue.

Parameters

  • workItem: Item to be processed.