AbstractService¶
-
class
kanzi::connect
::
AbstractService
: public MetaObject, public enable_shared_from_this<AbstractService>, public PropertyObject¶ Abstract base class for Kanzi Connect services.
Subclassed by ExternalServiceAdapter
Public Types
-
typedef map<string, EnumValues>
EnumMap
¶
-
typedef map<string, int>
EnumValues
¶
-
enum
InvokableOperationResult
¶ Values:
-
enumerator
Success
¶
-
enumerator
AlreadyExists
¶
-
enumerator
ValidationFailed
¶
-
enumerator
NotFound
¶
-
enumerator
NotReady
¶
-
enumerator
-
typedef function<void(AbstractService*)>
RuntimeDataSchemaChangeCallback
¶ Callback prototype to be invoked when runtime data schema changes.
-
typedef shared_ptr<void>
RuntimeDataSchemaChangeSubscriptionToken
¶ Handle given as return value to runtime data schema change callback registration.
-
enum
ServiceControlResult
¶ Values:
-
enumerator
ServiceControlSuccess
¶
-
enumerator
ServiceControlFailed
¶
-
enumerator
ServiceControlNotSupported
¶
-
enumerator
-
typedef enum kanzi::connect::AbstractService::ServiceControlResult
ServiceControlResult
-
enum
ServiceControlSource
¶ Values:
-
enumerator
ServiceControlSourceManual
¶
-
enumerator
ServiceControlSourceLogic
¶
-
enumerator
-
typedef enum kanzi::connect::AbstractService::ServiceControlSource
ServiceControlSource
-
typedef vector<AbstractSessionSharedPtr>
SessionContainer
¶ Container type for all connected sessions.
-
typedef function<void(AbstractService*)>
StateCallbackFunction
¶ Function prototype to be invoked when state changes.
-
typedef shared_ptr<void>
StateChangedSubscriptionToken
¶ Handle given as return value to state callback registration.
Public Functions
-
AbstractService
()¶ Constructor.
-
~AbstractService
()¶ Destructor.
-
AbstractSessionSharedPtr
acquireSession
(int clientId, int sessionId, MessageDispatcher *dispatcher, const string &instanceName)¶ Session factorization method.
- Return
newly allocated session. ownership not transfered.
- Parameters
clientId
: client identifier numbersessionId
: session identifier numberdispatcher
: message dispatching functionality for the session.instanceName
: name for the service/session instance
-
InvokableOperationResult
addCustomType
(const string &xml)¶ Add a custom type to the service.
- Return
InvokableOperationResult defining the success
- Parameters
xml
: Contains the xml definition for the custom type
-
InvokableOperationResult
addCustomTypeDecoded
(const string &decodedXml)¶ Add a custom type to the service.
- Return
InvokableOperationResult defining the success
- Parameters
decodedXml
: Contains the xml definition for the custom type in clear xml without base64 encoding
-
int
addEvent
(const string &identifier, const string &description)¶
-
int
addMethod
(const string &identifier, const string &description)¶
-
int
addProperty
(const string &identifier, const string &description)¶
-
InvokableOperationResult
addRoute
(const string &xml)¶ Add new P2P route(s) for the service.
- Return
InvokableOperationResult defining the success
- Parameters
xml
: Contains the xml definition for the route
-
InvokableOperationResult
addRouteDecoded
(const string &decodedXml)¶ Add new P2P route(s) for the service.
- Return
InvokableOperationResult defining the success
- Parameters
decodedXml
: Contains the xml definition for the route
-
RuntimeDataSchemaChangeSubscriptionToken
addRuntimeDataSchemaChangeSubscription
(RuntimeDataSchemaChangeCallback function)¶ Adds a callback to invoke when runtime data schema changes.
- Return
token that can be used to remove subscription
- Note
It is not allowed to destroy the service from the registered callback.
- Parameters
function
: function to be called on schema change.
-
StateChangedSubscriptionToken
addStateChangeSubscription
(StateCallbackFunction function)¶ Adds a state change callback subscription.
- Return
token that can be used to remove subscription
- Note
It is not allowed to destroy the service from the registered callback.
- Parameters
function
: function to be called on state change
Add subscription to the given session for this service.
- Return
True if subscription was added successfully, double subscription is not accepted
- Parameters
identifier
: Identifies the subscription, what this means is implementation specificsession
: The session to subscribe
-
void
cancelTimer
(int64_t timerId)¶ Cancels ongoing timer.
- Parameters
timerId
: identifier returned by the setTimer function.
-
int
countSessions
() const¶ Amount of allocated sessions.
- Return
amount of sessions
-
size_t
countSessions
()¶ Return the amount of sessions towards this service amount of sessions.
-
InvokableOperationResult
createRuntimedata
(const string &parentIdentifier, const string &xml)¶ Create a new runtime data element for the service runtime data.
- Return
Is the operation successful or not
- Parameters
parentIdentifier
: Specifies the parent under which create the element in the hierarchyxml
: Contains the xml defining the element contents
-
vector<AbstractSessionSharedPtr>
findSubscribers
(const string &identifier)¶ Find all subscribers for the given identifier.
- Return
vector listing all subscribers
- Parameters
identifier
: Identifies the subscriptions, what this means is implementation specific
-
const SessionContainer &
getAllSessions
() const¶ Returns all currently active sessions.
- Return
All sessions that are currently active.
-
SessionContainer
getAllSessionsOfClient
(int clientId)¶ Returns all sessions for a given client.
- Return
All sessions that were acquired for given client.
- Parameters
clientId
: Id of the client.
-
string
getAttribute
(const string &key)¶ Gets value of a service attribute.
- Return
The value of the attribute or an empty string.
- Parameters
key
: Name of the attribute
-
KanziStringVectorSharedPtr
getAttributes
()¶ Lists all service attributes.
- Return
flat list of service attributes, key and value follow in subsequent entries.
-
RuntimeDataObjectSharedPtr
getConfigurationProperties
()¶ Retrieves configuration properties as a runtime data object to allow more convenient access to data.
- Return
shared pointer to runtime data containing configuration properties.
-
ContentClientSharedPtr
getContentClient
() const¶ Access to content system.
- Return
Content client instance.
-
ContentProviderCollectionSharedPtr
getContentProvider
()¶ Returns content provider for this service.
- Return
Collection of content providers, created by this service.
-
const vector<unique_ptr<CustomType>> &
getCustomTypes
() const¶ Get the custom types defined for this service.
- Return
Vector containing the custom types
-
KanziStringVectorSharedPtr
getDisabledInvokables
()¶
-
ConnectDomainSharedPtr
getDomain
() const¶ Retrieves the connect domain.
- Return
the domain.
-
optional<int>
getEnumValue
(const string &name, const string &enumerator)¶ Find out value for enumeration string.
- Return
value if found.
- Parameters
name
: Name of the enum definition. Can be empty, first matching enumerator value is returned from all enumsenumerator
: Enumerator string, identifies the value
-
ServiceExtensionContainer *
getExtensions
()¶
-
string
getExtensionsSchemas
()¶
-
string
getFullyQualifiedConfigurationPropertyName
(const string &name)¶ Constructs a fully qualified configuration property name, usually the fully qualified name is something like “Connect.Service.MyService.ConfigurationProperties.MyPropertyName”.
- Return
fully qualified configuration property name.
- Parameters
name
: the name where the fully qualified name is to be composed
-
GenericInvoker *
getGenericInvoker
()¶ Retrieve a generic invoker bound to this service.
Lifetime of the object is the same as the service lifetime. Can be overridden by a class to rewrite functionality.
- Return
pointer to generic invoker. ownership not transfered.
-
string
getIdentifier
() const = 0¶
-
InterfaceDomainBase *
getInterfaceDomain
() const¶ Access to interface domain.
- Return
Interface domain pointer.
-
RuntimeDataObjectSharedPtr
getModifiedConfigurationProperties
()¶ Retrieves modified configuration properties as runtime data object.
Overriden by corresponding Concept class.
- Return
shared pointer to configuration properties that were modified since last called.
-
string
getName
()¶ Returns the override name.
- Return
the name that was explicitly set for the service.
-
WorkQueueInterface *
getProxyWorkQueue
()¶ Returns a proxied work queue instance that can be used by composited classes to to assign work to this service.
- Note
Returned interface will become invalid immediately when uninitialize() gets called for this Service.
- Return
pointer to interface that can be used dispatch event(s) to this particular service.
-
AbstractSessionSharedPtr
getRunningSession
()¶
-
string
getSchema
()¶ Returns service schema in XML format.
- Return
schema as xml.
-
const ServiceDescription &
getServiceDescription
() const¶ Access the static service description info.
- Return
reference to service information.
-
p2p::RoutingRulesSharedPtr
getServiceRoutingInformation
()¶ Return service routing information.
- Return
XML format string describing the preferred routing instructions.
-
const ServiceState &
getServiceState
() const¶ Gets service state information.
- Return
the state.
-
AbstractSessionSharedPtr
getSession
(int clientId, int sessionId)¶ Returns session by client & session id.
- Return
Session that was acquired with given parameters, or 0 if there was no such session.
- Parameters
clientId
: Id of the client.sessionId
: Id of the session.
-
int
getStopInterval
() const¶ Retrieve service stop interval.
- Return
stop interval in seconds.
-
WorkQueueInterface *
getWorkQueue
() const¶ Access to signal that allows to invoke work().
- Return
The signal.
-
bool
hasEnumValues
(const string &name)¶ Checks if enum has been defined on this service.
- Return
True if values have been registered for the name.
- Parameters
name
: Name of the enum definition.
-
bool
hasSubscriptions
(const string &identifier)¶ Check if the given identifier has any subscriptions.
- Return
True if at least one subscriber is found
- Parameters
identifier
: The identifier to check, what this means is implementation specific
Initialize this service.
- Parameters
domain
: Interface domain.contentClient
: Content Client that can be used to expose runtime state of this service to clients.workQueue
: Interface to system work queue used to dispatch work to services.
-
bool
manualPersistenceOverride
() const¶ Defines whether manual persistence override is active, i.e.
user has manually configured service to a state and thus automatic shutdown is not active.
- Return
true if current state is set manually.
-
AbstractSessionSharedPtr
onAcquireSession
(int clientId, int sessionId, MessageDispatcher *dispatcher, const string &instanceName) = 0¶ Session factorization method interface.
To be overrided by concrete services
- Return
newly allocated session. ownership is transfered.
- Parameters
clientId
: client identifier numbersessionId
: session identifier numberdispatcher
: message dispatching functionality for the session.instanceName
: name for the service/session instance
Virtual method that inheriting classes can implement.
Can be used to receive notifications when sessions are destroyed.
- Parameters
session
: identifies the session to be released. ownership not transfered.
Offer received message directly to service to implement a short path for scripts and built-in methods. Intended for internal use.
-
void
releaseAllSessions
()¶ Unconditionally releases all sessions. use carefully.
Releases previously allocated session.
- Parameters
session
: the session to release. ownership not transfered.
-
InvokableOperationResult
removeCustomType
(const string &typeName)¶ Remove a custom type from a service.
- Return
InvokableOperationResult defining the success
- Parameters
typeName
: The name of the type
-
int
removeEvent
(const string &identifier)¶
-
int
removeMethod
(const string &identifier)¶
-
int
removeProperty
(const string &identifier)¶
-
InvokableOperationResult
removeRoute
(const string &subjectName)¶ Remove a route from a service.
- Return
InvokableOperationResult defining the success
- Parameters
subjectName
: The subject of the route (can be method name, event name or “runtimedata”)
-
InvokableOperationResult
removeRuntimedataElement
(const string &elementIdentifier)¶ Remove runtime data element from the service runtime data.
- Return
Is the operation successful or not
- Parameters
elementIdentifier
: Specifies which element to remove
-
void
removeRuntimeDataSchemaChangeSubscription
(RuntimeDataSchemaChangeSubscriptionToken token)¶ Remove schema change subscription.
- Parameters
token
: to remove.
-
void
removeStateChangeSubscription
(StateChangedSubscriptionToken token)¶ Remove state change subscription.
- Parameters
token
: to remove.
Remove subscription to the given session for this service.
- Return
Vector containing identifiers that no longer have any subscriptions left after this call
- Parameters
session
: The session whose subscriptions are to be removedidentifier
: The subscriptions to remove, if empty all subscriptions for the session are removed
Tries to reset service.
Return value indicates the status of execution.
- Return
status indicating the success of the operation. It is up to the service to decide what “reset” means to it.
- Parameters
arguments
: optional arguments passed along with the control request.
-
ServiceRuntimeData &
runtimeData
()¶ Retrieve service runtime data.
- Return
reference to services runtime data.
-
void
setAttribute
(const string &key, const string &value)¶ Add service attributes as key value pairs.
These will be visible on service description, but don’t affect runtime state
Set the connect domain.
- Parameters
domain
: the domain
-
void
setFileClient
(VirtualFileClient *client)¶ Set the client instance to access VirtualFileService.
- Parameters
client
: Pointer to the instance which is used to access the service
-
void
setName
(const string &name)¶ Defines a override name used to identify the service.
- Parameters
name
: the name
-
void
setPersistence
(AbstractService::ServiceDescription::Persistence persistence)¶ Sets the service persistence.
- Parameters
persistence
: the persistence type for the service.
Stores the currently running session.
Should not be called from 3rd party code - used only internally by the infrastructure.
-
InvokableOperationResult
setRuntimedataValue
(const string &elementIdentifier, const string &value)¶ Set runtime data value for the given element in the service runtime data.
- Parameters
elementIdentifier
: Identifies the element in the service runtime datavalue
: The value to set in serialized format
-
bool
setServiceRuntimeDataSchema
(const string &xml)¶ Set service runtime data schema.
All previously configured runtime data specific settings are discarded. New schema is also delivered to client(s).
- Return
true if succeeded. false if problems.
- Parameters
xml
: XML format schema
-
void
setServiceState
(AbstractService::ServiceState state)¶ sets service state information.
- Parameters
state
: the state
-
void
setServiceVersion
(AbstractService::ServiceDescription::Version version, AbstractService::ServiceDescription::Version minCompatibleVersion = AbstractService::ServiceDescription::Version())¶ Configures the service version information.
This should be called in constructor.
- Parameters
version
: the main version of the serviceminCompatibleVersion
: minimum compatible version.
-
void
setSettingFactory
(const persistence::SettingFactory *factory)¶ Set the setting factory instance to allow using persistence service.
- Parameters
factory
: Pointer to the instance which is used to instantiate setting objects
-
void
setStopInterval
(int seconds)¶ Configures the stop interval.
- Parameters
seconds
: the value to set. Negative values are rounded to 0.
-
int64_t
setTimer
(int64_t milliseconds, ConnectWorkItem::Executor callback)¶ Installs a timer to be called after a specified timeout in milliseconds.
- Return
handle that can then be used cancel the timer.
- Parameters
milliseconds
: timeout in millisecondscallback
: function to be called when timer expires.
-
int64_t
setTimer
(int64_t milliseconds, ConnectWorkItem::Executor callback, ConnectWorkItem::ExecutionContext executionContext)¶ Installs a timer to be called after a specified timeout in milliseconds.
- Return
handle that can then be used cancel the timer.
- Parameters
milliseconds
: timeout in millisecondscallback
: function to be called when timer expires.executionContext
: Defines in which thread the callback should be executed.
-
bool
simulateEvent
(const string &messageName, const MessagePackage &message)¶ Post a message to all running sessions as event. Intended for internal use.
Tries to start the service.
Return value indicates if operation fails
- Return
true if service got running. false indicates a failure in that operation.
- Parameters
serviceControlSource
: what caused the service control to be accomplished.arguments
: the arguments to use when starting the service. Similar to command line arguments on shell - effectively a list of strings.
-
AbstractService::ServiceControlResult
stopService
(ServiceControlSource serviceControlSource)¶ Tries to stop the service.
Shall the stop fail or otherwise not supported then scenario must be indicated with return value
- Return
true if service got stopped or it was stopped already. false if unable to stop the service.
- Parameters
serviceControlSource
: what caused the service control to be accomplished.
-
void
uninitialize
()¶ Uninitialize this service.
- Note
Classes that inherit AbstractService class must call this base class implementation if their override this method.
Asks service to perform work.
-
class
ServiceDescription
¶ Public Types
-
enum
Persistence
¶ Values:
-
enumerator
StartOnDemand
¶ Service starts and shutdowns automatically when clients connect/disconnect.
-
enumerator
AlwaysRunning
¶ Service is always running regardless whether there are any clients connected.
-
enumerator
-
typedef enum kanzi::connect::AbstractService::ServiceDescription::Persistence
Persistence
Public Functions
-
ServiceDescription
(ServiceDescription::Version version = ServiceDescription::Version(), ServiceDescription::Version minVersion = ServiceDescription::Version(), ServiceDescription::Persistence persistence = AlwaysRunning)¶ C++ constructor.
- Parameters
version
: default versionminVersion
: minimum acceptable version
-
bool
valid
() const¶ Is the object validly constructed.
Public Members
-
bool
m_manualPersistenceOverride
¶ Whether persistence functionality has been manually overridden.
-
Persistence
m_persistence
¶ Execution type.
-
class
Version
¶ Encapsulates version information.
Public Functions
-
Version
(int major = InvalidVersionNumber, int minor = InvalidVersionNumber)¶ c++ constructor.
initialize object.
- Parameters
major
: major numberminor
: minor number
-
Version
(const string versionstr)¶ constructs object from version string
- Parameters
versionstr
: version in format “1.2”
-
string
toString
() const¶ Converts version information to string.
- Return
version as string “1.0”
-
bool
valid
() const¶ Is version number valid.
- Return
true if version is valid.
Public Members
-
int
m_major
¶ major version number “X.something”
-
int
m_minor
¶ Minor version number “something.Y”.
Friends
-
-
enum
-
class
ServiceState
¶ Public Types
Public Functions
-
bool
initialized
() const¶ Checks whether service has been successfully initialized.
- Return
true if service is initialized.
-
bool
running
() const¶ Checks whether service is running.
- Return
true if service is running.
-
bool
stopped
() const¶ Checks whether service is stopped.
- Return
true if service is stopped.
-
bool
-
typedef map<string, EnumValues>