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

inline ServiceHost(ServiceRuntimeDataRegistrySharedPtr registry = ServiceRuntimeDataRegistrySharedPtr())

C++ constructor.

Parameters

  • registry: runtime data registry.

virtual ~ServiceHost()

Destructor.

virtual 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.

virtual void changeType(const string &type) = 0

Changes the interface name at runtime.

Parameters

  • type: new type for the interface.

virtual int clientID() const = 0

Returns the client identifier.

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

Return

client identifier.

virtual int countSessions() const = 0

Returns amount of sessions towards this service.

Return

amount of sessions

inline virtual 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.

virtual ClientDescriptorSharedPtr getClientDescriptor() = 0

Return the client descriptor.

Relevant only for remote services.

Return

client descriptor

virtual RuntimeDataObjectSharedPtr getConfigurationProperties() = 0

Retrieve service configuration properties.

Return

properties as shared object.

virtual const AbstractService::ServiceDescription &getDescription() = 0

Retrieve the service description from service host.

Return

const reference to service description

virtual string getIdentifier() const = 0

Retrieve interface identifier.

Return

interface ID this service handles.

inline virtual 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.

virtual AbstractServiceSharedPtr getService() const = 0

Returns a service instance.

Relevant only for local services.

Return

service

virtual 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.

virtual string getServiceRoutingInformationDescription(int serverclientid) = 0

Must be overridden by the corresponding implementation.

Return

xml format routing information for the service.

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

Returns a session to remote service.

Relevant only for remote services.

Return

session

virtual const AbstractService::ServiceState &getState() = 0

Retrieve the service state information.

Return

const reference to service state information.

virtual 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.

virtual bool local() const = 0

Is this service local or not.

Return

true if service is local

inline virtual void notifyAll(const MessagePackage&)

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

Notify all client sessions with message.

virtual void notifyClientDisconnected(int clientId) = 0

Invoked to inform that specific client has disconnected.

Parameters

  • clientId: Identifies the client.

virtual 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.

virtual bool registerServiceRuntimeData(const string schema = "")

Invoked to register service runtime data.

Return

true if registered successfully.

Parameters

  • schema: the schema (xml)

virtual bool registerServiceRuntimeDataSchemaChange(const string &xml)

Invoked to change runtime data schema at runtime.

Return

true on success.

Parameters

  • xml: the xml structure

virtual void releaseSession(int clientId, int sessionId) = 0

Releases a session.

Parameters

  • clientId: identifies the client

  • sessionId: identifies the session

inline virtual bool reportServiceRuntimeData(const string&, const string&)

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

inline virtual 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.

virtual void setConfigurationPropertyChangedCallback(ConfigurationPropertyChangedCallback callback)

Install a callback to be invoked when configuration property changes.

Parameters

  • callback: to be invoked.

virtual 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

virtual 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

virtual 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.