Info

Introspection helpers: retrieve a gobj’s name, short name, full name, parent, yuno, and other metadata used by tooling and logs.

Source code:

• gobj.h

• gobj.c

get_attrs_schema()¶

Returns a JSON array describing the attributes of a given hgobj. The attributes included are those marked with SDF_RD, SDF_WR, SDF_STATS, SDF_PERSIST, SDF_VOLATIL, SDF_RSTATS, or SDF_PSTATS.

json_t *get_attrs_schema(hgobj gobj);

Parameters

Returns

A JSON array where each element is an object containing details about an attribute, including its name, type, flags, and description.

Notes

The returned JSON array must be freed by the caller using json_decref().

get_sdata_flag_table()¶

Returns a table of sdata (structured data) flag names as a null-terminated array of strings.

const char **get_sdata_flag_table(void);

Parameters

Returns

A pointer to a null-terminated array of strings representing sdata flag names.

Notes

The returned array contains predefined flag names used in structured data attributes. The caller should not modify or free the returned pointer.

gobj2json()¶

Returns a JSON object containing a structured description of the given gobj, including attributes, state, and metadata.

json_t *gobj2json(
    hgobj gobj,
    json_t *jn_filter // owned
);

Parameters

Returns

A JSON object containing the requested details of gobj. The caller owns the returned JSON object and must free it when done.

Notes

The jn_filter parameter allows selective inclusion of attributes such as fullname, state, attrs, and gobj_flags. If jn_filter is empty, all available attributes are included.

gobj_command_desc()¶

Retrieves the command description for a given gobj. If the command name is NULL, it returns the full command table.

const sdata_desc_t *gobj_command_desc(
    hgobj gobj,
    const char *name,
    BOOL verbose
);

Parameters

Returns

A pointer to the sdata_desc_t structure describing the command, or NULL if the command is not found.

Notes

This function first checks if the gobj is valid. If the command name is NULL, it returns the full command table. Otherwise, it searches for the specific command in the gobj’s gclass.

gobj_full_name()¶

Returns the full hierarchical name of the given hgobj, constructed from its ancestors using the ‘`’ separator.

const char *gobj_full_name(hgobj gobj);

Parameters

Returns

A pointer to a statically allocated string containing the full hierarchical name of the hgobj. Returns ‘???’ if the object is NULL or destroyed.

Notes

The returned string is managed internally and should not be modified or freed by the caller.

gobj_gclass()¶

Returns the gclass associated with the given hgobj.

hgclass gobj_gclass(hgobj gobj);

Parameters

Returns

Returns the hgclass associated with the given hgobj, or NULL if the input is invalid.

Notes

This function does not perform extensive validation on the input hgobj. Ensure that the object is properly initialized before calling this function.

gobj_gclass_name()¶

Retrieves the gclass name associated with the given hgobj.

gclass_name_t gobj_gclass_name(hgobj gobj);

Parameters

Returns

Returns the gclass name of the given hgobj. If gobj is NULL, returns ???.

Notes

This function does not perform any validation beyond checking for NULL.

gobj_global_variables()¶

Returns a JSON object containing global variables related to the Yuno environment, including system, realm, and node attributes.

json_t *gobj_global_variables(void);

Parameters

Returns

A JSON object containing the following global variables:

Notes

The returned JSON object must be decremented with json_decref() to avoid memory leaks. These variables are also available for substitution in configuration strings via the (^^ ^^) syntax — see Settings.

gobj_is_destroying()¶

Checks if the given hgobj is in the process of being destroyed or has already been destroyed.

BOOL gobj_is_destroying(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is being destroyed or has already been destroyed, otherwise returns FALSE.

Notes

This function is useful for preventing operations on objects that are no longer valid.

gobj_is_disabled()¶

Checks if the given hgobj is disabled. A disabled hgobj is prevented from starting or playing.

BOOL gobj_is_disabled(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is disabled, otherwise returns FALSE.

Notes

A disabled hgobj cannot be started or played until it is explicitly enabled using gobj_enable().

gobj_is_playing()¶

Checks if the given hgobj is currently in a playing state.

BOOL gobj_is_playing(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is playing, otherwise returns FALSE.

Notes

If the hgobj is NULL or has been destroyed, an error is logged and FALSE is returned.

gobj_is_pure_child()¶

Checks if the given hgobj is marked as a pure child, meaning it sends events directly to its parent instead of publishing them.

BOOL gobj_is_pure_child(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is a pure child, otherwise returns FALSE.

Notes

A pure child is a hgobj that bypasses event publication and directly sends events to its parent.

gobj_is_running()¶

Checks if the given hgobj instance is currently running.

BOOL gobj_is_running(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is running, otherwise returns FALSE.

Notes

If the provided hgobj is NULL or has been destroyed, an error is logged and FALSE is returned.

gobj_is_service()¶

Checks if the given hgobj is marked as a service. A service object is an interface available for external access.

BOOL gobj_is_service(hgobj gobj);

Parameters

Returns

Returns TRUE if the object is a service, otherwise returns FALSE.

Notes

A service object is identified by the gobj_flag_service flag.

gobj_is_volatil()¶

Checks if the given hgobj is marked as volatile, meaning it is temporary and can be automatically destroyed.

BOOL gobj_is_volatil(hgobj gobj);

Parameters

Returns

Returns TRUE if the hgobj is volatile, otherwise returns FALSE.

Notes

A volatile hgobj is typically used for temporary objects that do not persist beyond their immediate use.

gobj_name()¶

Returns the name of the given hgobj instance as a string.

const char *gobj_name(hgobj gobj);

Parameters

Returns

A pointer to a string containing the name of the hgobj instance. If gobj is NULL, returns “???”.

Notes

The returned string is managed internally and should not be modified or freed by the caller.

gobj_parent()¶

Returns the parent object of the given hgobj.

hgobj gobj_parent(hgobj gobj);

Parameters

Returns

Returns the parent hgobj of the given object, or NULL if the object has no parent.

Notes

If the provided hgobj is NULL, an error is logged.

gobj_priv_data()¶

Returns a pointer to the private data of the given hgobj.

void *gobj_priv_data(hgobj gobj);

Parameters

Returns

A pointer to the private data associated with the given hgobj.

Notes

The returned pointer provides direct access to the private data structure of the hgobj. Ensure that the hgobj is valid before accessing its private data.

gobj_set_volatil()¶

Sets or clears the gobj_flag_volatil flag for the given hgobj instance.

int gobj_set_volatil(
    hgobj gobj, 
    BOOL set
);

Parameters

Returns

Returns 0 on success.

Notes

A volatile hgobj is typically used for temporary objects that should not persist beyond a certain scope.

gobj_short_name()¶

Returns the short name of the given hgobj, formatted as gclass^name.

const char * gobj_short_name(
    hgobj gobj
);

Parameters

Returns

A pointer to a string containing the short name of the object. If the object is NULL or destroyed, returns ???.

Notes

The short name is generated dynamically and cached for future calls.

gobj_typeof_gclass()¶

Checks if the given hgobj belongs to the specified gclass.

BOOL gobj_typeof_gclass(
    hgobj gobj,
    const char *gclass_name
);

Parameters

Returns

Returns TRUE if the hgobj belongs to the specified gclass, otherwise returns FALSE.

Notes

This function performs a strict comparison against the object’s gclass and does not check for inherited gclasses.

gobj_typeof_inherited_gclass()¶

Checks if the given hgobj belongs to a specific inherited gclass.

BOOL gobj_typeof_inherited_gclass(
    hgobj gobj,
    const char *gclass_name
);

Parameters

Returns

Returns TRUE if the gobj or any of its inherited (bottom) gobjs belong to the specified gclass, otherwise returns FALSE.

Notes

This function traverses the bottom gobj hierarchy to determine if any of them match the given gclass_name.

gobj_view_tree()¶

Generates a hierarchical JSON representation of the given hgobj and its child objects, including selected attributes.

json_t *gobj_view_tree(
    hgobj gobj,
    json_t *jn_filter // owned
);

Parameters

Returns

A JSON object representing the hierarchical structure of gobj and its children, including the requested attributes.

Notes

The returned JSON object must be freed by the caller. The jn_filter parameter allows selective inclusion of attributes such as fullname, state, attrs, etc.

gobj_yuno()¶

Returns the root gobj instance representing the Yuno, which is the top-level object in the hierarchy.

hgobj gobj_yuno(void);

Parameters

Returns

A handle to the Yuno gobj instance, or NULL if the Yuno has not been initialized or has been destroyed.

Notes

The Yuno is the top-most gobj in the hierarchy and serves as the root of the object tree.

gobj_yuno_id()¶

Returns the unique identifier of the Yuno instance.

const char *gobj_yuno_id(void);

Parameters

Returns

A string representing the unique identifier of the Yuno instance.

Notes

If the Yuno instance is not initialized, an empty string is returned.

gobj_yuno_name()¶

Returns the name of the Yuno instance by retrieving the name attribute from gobj_yuno().

const char *gobj_yuno_name(void);

Parameters

Returns

A string representing the name of the Yuno instance. Returns an empty string if the Yuno instance is not available.

Notes

[‘This function retrieves the name attribute from the Yuno instance returned by gobj_yuno().’, ‘If gobj_yuno() returns NULL, an empty string is returned.’]

gobj_yuno_node_owner()¶

Returns the node owner of the Yuno instance as a string.

const char *gobj_yuno_node_owner(void);

Parameters

Returns

A pointer to a string containing the node owner of the Yuno instance. If the Yuno instance is not available, an empty string is returned.

Notes

This function retrieves the value of the node_owner attribute from the Yuno instance.

gobj_yuno_realm_env()¶

Returns the realm environment of the Yuno instance.

const char *gobj_yuno_realm_env(void);

Parameters

Returns

A string representing the realm environment of the Yuno instance. Returns an empty string if the Yuno instance is not available.

Notes

This function retrieves the value of the realm_env attribute from the Yuno instance.

gobj_yuno_realm_id()¶

Returns the realm ID of the Yuno instance.

const char *gobj_yuno_realm_id(void);

Parameters

Returns

A string representing the realm ID of the Yuno instance. Returns an empty string if the Yuno instance is not available.

Notes

The function retrieves the value from the realm_id attribute of the Yuno object, which is the root object in the GObj hierarchy.

gobj_yuno_realm_name()¶

Returns the realm name of the Yuno instance.

const char *gobj_yuno_realm_name(void);

Parameters

Returns

A string representing the realm name of the Yuno instance. Returns an empty string if the Yuno instance is not available.

Notes

The function retrieves the value of the realm_name attribute from the Yuno instance.

gobj_yuno_realm_owner()¶

Returns the realm owner of the current Yuno instance.

const char *gobj_yuno_realm_owner(void);

Parameters

Returns

A string representing the realm owner of the Yuno instance. If the Yuno instance is not available, an empty string is returned.

Notes

The function retrieves the value from the realm_owner attribute of the Yuno instance.

gobj_yuno_realm_role()¶

Returns the realm role of the current yuno instance.

const char *gobj_yuno_realm_role(void);

Parameters

Returns

A string representing the realm role of the yuno instance. If the yuno instance is not available, an empty string is returned.

Notes

[‘The function retrieves the value of the realm_role attribute from the yuno instance.’, ‘If the yuno instance is not initialized, it returns an empty string.’]

gobj_yuno_role()¶

Returns the role of the current Yuno instance as a string.

const char *gobj_yuno_role(void);

Parameters

Returns

A string representing the role of the Yuno instance. If the Yuno instance is not available, an empty string is returned.

Notes

The function retrieves the value of the yuno_role attribute from the Yuno instance using gobj_read_str_attr().

gobj_yuno_role_plus_name()¶

Returns the concatenated role and name of the Yuno instance.

const char *gobj_yuno_role_plus_name(void);

Parameters

Returns

A string containing the Yuno’s role and name concatenated.

Notes

If the Yuno instance is not initialized, an empty string is returned.

gobj_yuno_tag()¶

Returns the tag of the current yuno instance as a string.

const char *gobj_yuno_tag(void);

Parameters

Returns

A pointer to a string containing the yuno tag. If the yuno instance is not available, an empty string is returned.

Notes

The returned string is managed internally and should not be modified or freed by the caller.

gobj_audit_commands()¶

Registers a global callback function that will be invoked every time a command is executed. This enables auditing or logging of all commands processed by the gobj system. Only one audit callback can be active at a time -- subsequent calls overwrite the previously registered callback.

int gobj_audit_commands(
    int (*audit_command_cb)( const char *command, json_t *kw, void *user_data ),
    void *user_data
);

Parameters

Returns

Returns 0 on success.

Notes

Only one audit callback is supported globally. Each new call to gobj_audit_commands() replaces the previous callback and user data.

gobj_is_bottom_gobj()¶

Checks whether the given gobj is the bottom gobj of its parent. A bottom gobj is a special child that provides attribute inheritance -- when an attribute is not found on the parent, the framework delegates to the bottom gobj.

BOOL gobj_is_bottom_gobj(
    hgobj gobj
);

Parameters

Returns

Returns TRUE if the gobj is its parent’s designated bottom gobj, FALSE otherwise (including when gobj is NULL or has no parent).

Notes

The bottom gobj relationship is set during gobj creation. Use gobj_bottom_gobj() to retrieve the bottom gobj of a given parent.

gobj_is_top_service()¶

Checks whether the given gobj is a top-level service. A top service is a service gobj that was created with the gobj_flag_top_service flag, typically representing the highest-level service in a yuno’s gobj tree.

BOOL gobj_is_top_service(
    hgobj gobj
);

Parameters

Returns

Returns TRUE if the gobj has the gobj_flag_top_service flag set, FALSE otherwise.

Notes

A top service differs from a regular service (gobj_is_service()) in that it represents the primary entry point for a yuno. Use gobj_top_services() to list all top services.

gobj_kw_get_user_data()¶

Retrieves a value from the gobj’s user data dictionary by path. The user data is a free-form JSON object associated with each gobj where application-specific data can be stored (via gobj_kw_set_user_data()).

json_t *gobj_kw_get_user_data(
    hgobj gobj,
    const char *path,
    json_t *default_value,
    kw_flag_t flag
);

Parameters

Returns

The JSON value at the given path, or default_value if not found. The return value is NOT owned by the caller unless KW_EXTRACT is used in flag.

Notes

This function delegates to kw_get_dict_value() on the gobj’s internal jn_user_data dictionary. Returns NULL if gobj is NULL.

gobj_nearest_top_service()¶

Walks up the gobj tree from the given gobj’s parent and returns the nearest ancestor that is a service, top service, or the yuno itself. This is useful for finding the enclosing service context of any gobj.

hgobj gobj_nearest_top_service(
    hgobj gobj
);

Parameters

Returns

A handle to the nearest ancestor gobj that is a service, top service, or __yuno__. Returns NULL if gobj is NULL or destroyed.

Notes

The traversal checks for gobj_flag_service, gobj_flag_top_service, or gobj_flag_yuno flags on each ancestor. The search begins at the parent of the provided gobj.

gobj_top_services()¶

Returns a JSON array listing all currently registered top-level service gobjs and their metadata. Each element is a JSON object containing the GClass name, service name, gobj handle, priority, and gobj flags.

json_t *gobj_top_services(void);

Parameters

Returns

A new JSON array (owned by the caller) where each element is a JSON object with keys: "gclass" (string), "service" (string), "gobj" (integer handle), "priority" (integer), and "gobj_flag" (integer).

Notes

Only services with the gobj_flag_top_service flag are included. Regular services (without the top flag) are excluded. Use gobj_services() to list all registered services including non-top ones.