Coldwave Documentation

Appearance

class flake::Object ​

Client-side proxy for a Flake object. More...

#include <platform/flake/Object.h>

Public Functions ​

Name
virtual intregistered() =0
Check whether the object is registered with the router.
virtual intinvoke(const std::string & command, PropArray & params, bool blocking, PropArray & reply) =0
Invoke a named custom function on the object.
virtual intbroadcast(const std::string & command, PropArray & params) =0
Broadcast a named custom message to all subscribers.
virtual intgetProperties(PropArray & properties) =0
Retrieve all properties of the object.
virtual intsetProperties(PropArray & properties) =0
Set multiple properties on the object in one call.
virtual intsetProperty(constProperty & property) =0
Set a single property on the object.
virtual voidgetProperty(Property & property) =0
Read a single property from the local cache.
virtual intopenProperty(constuint32_t propTag, Stream ** stream) =0
Open a stream associated with a stream-typed property.
virtual intsubscribe(std::function< void(constIndication &)> f) =0
Subscribe to property-change notifications.
virtual voidunsubscribe() =0
Remove all subscriptions from this object.
virtual intsync(unsigned timeout_ms, bool block) =0
Flush all pending local property changes to the router.
virtual voiddefer() =0
Move all pending local property changes into a deferred buffer instead of syncing immediately.
virtual intsyncDeferred(unsigned timeout_ms, bool block) =0
Flush all deferred property changes to the router.
virtual boolhasDeferred() =0
Check whether there are deferred property changes waiting.
virtual voidclear() =0
Discard all pending and deferred local property changes.
virtual voidref() =0
Increment the reference count.
virtual voidunref() =0
Decrement the reference count.

Protected Functions ​

Name
Object() =default
~Object() =default
virtual ObjectImpl *impl() =0
Access the internal implementation.

Friends ​

Name
classConnectionImpl(ConnectionImpl )

Detailed Description ​

cpp
class flake::Object;

Client-side proxy for a Flake object.

Note: Non-copyable, non-movable.

Par: Ownership

Every Object obtained from queryObjects() starts with a reference count of 1. Call ref() / unref() to manage the lifetime. When the count reaches zero the Object is returned to the internal pool.

Object instances are obtained from Connection::queryObjects(). They provide property access, remote invocation, subscription, and stream opening.

Public Functions Documentation ​

function registered ​

cpp
virtual int registered() =0

Check whether the object is registered with the router.

Return: E_OK if registered, or a negative error code.

function invoke ​

cpp
virtual int invoke(
    const std::string & command,
    PropArray & params,
    bool blocking,
    PropArray & reply
) =0

Invoke a named custom function on the object.

Parameters:

  • command Name of the function to invoke.
  • params Input parameters as a PropArray.
  • blocking If true, block until the result is received; set to false for fire-and-forget ("void") calls.
  • reply Output parameters populated by the callee (only meaningful when blocking is true).

Return: E_OK on success, or a negative error code.

Custom functions are implementation-defined and not part of any standard device class.

function broadcast ​

cpp
virtual int broadcast(
    const std::string & command,
    PropArray & params
) =0

Broadcast a named custom message to all subscribers.

Parameters:

  • command Name of the message.
  • params Message parameters as a PropArray.

Return: E_OK on success, or a negative error code.

Custom messages are implementation-defined and not part of any standard device class.

function getProperties ​

cpp
virtual int getProperties(
    PropArray & properties
) =0

Retrieve all properties of the object.

Parameters:

  • properties PropArray that receives the current property values.

Return: E_OK on success, or a negative error code.

function setProperties ​

cpp
virtual int setProperties(
    PropArray & properties
) =0

Set multiple properties on the object in one call.

Parameters:

  • properties PropArray of properties to set. On return, each property may carry an error tag if it could not be applied.

Return: E_OK on success, or a negative error code.

function setProperty ​

cpp
virtual int setProperty(
    constProperty & property
) =0

Set a single property on the object.

Parameters:

  • property The property to set.

Return: E_OK on success, or a negative error code.

The property is not sent to the router immediately; it is cached locally until sync() or defer() / syncDeferred() is called.

function getProperty ​

cpp
virtual void getProperty(
    Property & property
) =0

Read a single property from the local cache.

Parameters:

  • property On entry, the tag identifies which property to read. On return, the value is filled in.

If the property has not been fetched yet the returned Property will carry a TAG_NULL flag.

function openProperty ​

cpp
virtual int openProperty(
    constuint32_t propTag,
    Stream ** stream
) =0

Open a stream associated with a stream-typed property.

Parameters:

  • propTag Tag of a TT_STRING_STREAM or TT_BIN_STREAM property.
  • stream Receives a pointer to the opened Stream.

Return: E_OK on success, or a negative error code.

function subscribe ​

cpp
virtual int subscribe(
    std::function< void(constIndication &)> f
) =0

Subscribe to property-change notifications.

Parameters:

  • f Callback invoked whenever the object's properties change.

Return: E_OK on success, or a negative error code.

function unsubscribe ​

cpp
virtual void unsubscribe() =0

Remove all subscriptions from this object.

function sync ​

cpp
virtual int sync(
    unsigned timeout_ms,
    bool block
) =0

Flush all pending local property changes to the router.

Parameters:

  • timeout_ms Maximum wait time in milliseconds.
  • block If true, wait synchronously for the router's confirmation.

Return: E_OK on success, or a negative error code.

Properties set via setProperty() are batched locally. Calling sync() sends them in a single transaction.

function defer ​

cpp
virtual void defer() =0

Move all pending local property changes into a deferred buffer instead of syncing immediately.

Deferred changes accumulate and can later be flushed with syncDeferred().

function syncDeferred ​

cpp
virtual int syncDeferred(
    unsigned timeout_ms,
    bool block
) =0

Flush all deferred property changes to the router.

Parameters:

  • timeout_ms Maximum wait time in milliseconds.
  • block If true, wait synchronously.

Return: E_OK on success, or a negative error code.

function hasDeferred ​

cpp
virtual bool hasDeferred() =0

Check whether there are deferred property changes waiting.

Return: true if deferred data exists, false otherwise.

function clear ​

cpp
virtual void clear() =0

Discard all pending and deferred local property changes.

function ref ​

cpp
virtual void ref() =0

Increment the reference count.

Every ref() must be balanced by a corresponding unref().

function unref ​

cpp
virtual void unref() =0

Decrement the reference count.

When the count reaches zero the object is destroyed / returned to the pool.

Protected Functions Documentation ​

function Object ​

cpp
Object() =default

function ~Object ​

cpp
~Object() =default

function impl ​

cpp
virtual ObjectImpl * impl() =0

Access the internal implementation.

Friends ​

friend ConnectionImpl ​

cpp
friend class ConnectionImpl(
    ConnectionImpl 
);