QrtrBus: libqrtr-glib Reference Manual

## QrtrBus QrtrBus — QRTR bus observer and device event listener |

## Functions

void | qrtr_bus_new ()
QrtrBus * | qrtr_bus_new_finish ()
QrtrNode * | qrtr_bus_peek_node ()
QrtrNode * | qrtr_bus_get_node ()
GList * | qrtr_bus_get_nodes ()
GList * | qrtr_bus_peek_nodes ()
void | qrtr_bus_wait_for_node ()
QrtrNode * | qrtr_bus_wait_for_node_finish ()

## Properties

guint | lookup-timeout | Read / Write / Construct Only

## Signals

void | node-added | Run Last
void | node-removed | Run Last

## Types and Values

#define | QRTR_BUS_LOOKUP_TIMEOUT
#define | QRTR_BUS_SIGNAL_NODE_ADDED
#define | QRTR_BUS_SIGNAL_NODE_REMOVED
| QrtrBus

## Object Hierarchy

        GObject
        ╰── QrtrBus

## Implemented Interfaces

QrtrBus implements GAsyncInitable.

## Description

QrtrBus sets up a socket that uses the QRTR IPC protocol and can call back into a client to tell them when new devices have appeared on the QRTR bus. It holds QrtrNodes that can be used to look up service and port information.

## Functions

### qrtr_bus_new ()

    void
    qrtr_bus_new (guint lookup_timeout_ms,
                  GCancellable *cancellable,
                  GAsyncReadyCallback callback,
                  gpointer user_data);

Asynchronously creates a QrtrBus object.

This method will fail if the access to the QRTR bus is not possible, or if the initial lookup doesn't finish on time.

When `lookup_timeout_ms` is 0, this method does not guarantee that the initial bus lookup has already finished, the user should wait for the required “node-added” and “service-added” signals before assuming the nodes are accessible.

When the operation is finished, `callback` will be invoked. You can then call `qrtr_bus_new_finish()` to get the result of the operation.

#### Parameters

lookup_timeout_ms | the timeout, in milliseconds, to wait for the initial bus lookup to complete. A zero timeout disables the lookup. |
cancellable | optional GCancellable object, `NULL` to ignore. |
callback | a GAsyncReadyCallback to call when the initialization is finished. |
user_data | the data to pass to callback function. |

Since: 1.0

### qrtr_bus_new_finish ()

    QrtrBus *
    qrtr_bus_new_finish (GAsyncResult *res,
                         GError **error);

Finishes an operation started with `qrtr_bus_new()`.

#### Parameters

res | a GAsyncResult. |
error | Return location for error or `NULL`. |

#### Returns

A newly created QrtrBus, or `NULL` if `error` is set.

[transfer full]

Since: 1.0

### qrtr_bus_peek_node ()

    QrtrNode *
    qrtr_bus_peek_node (QrtrBus *self,
                        guint32 node_id);

Get the QrtrNode with node ID `node_id` , without increasing the reference count on the returned object.

This method will fail if there is no node with the given `node_id` in the QRTR bus.

#### Parameters

self | a QrtrBus. |
node_id | the QRTR bus node ID to get |

#### Returns

a QrtrNode, or `NULL` if none available. Do not free the returned object, it is owned by `self` .

[transfer none]

Since: 1.0

### qrtr_bus_get_node ()

    QrtrNode *
    qrtr_bus_get_node (QrtrBus *self,
                       guint32 node_id);

Get the QrtrNode with node ID `node_id` .

This method will fail if there is no node with the given `node_id` in the QRTR bus.

#### Parameters

self | a QrtrBus. |
node_id | the QRTR bus node ID to get |

#### Returns

a QrtrNode that must be freed with `g_object_unref()`, or `NULL` if none available.

[transfer full]

Since: 1.0

### qrtr_bus_get_nodes ()

    GList *
    qrtr_bus_get_nodes (QrtrBus *self);

Gets a list of all the QrtrNode objects in the bus.

#### Parameters

self | a QrtrBus. |

#### Returns

a list of QrtrNode elements. The caller should free the result by using `g_list_free_full()` with `g_object_unref()` as GDestroyNotify.

[transfer full][nullable][element-type QrtrNode]

Since: 1.0

### qrtr_bus_peek_nodes ()

    GList *
    qrtr_bus_peek_nodes (QrtrBus *self);

Gets a list of all the QrtrNode objects in the bus, without increasing the reference count on the returned object or the list.

#### Parameters

self | a QrtrBus. |

#### Returns

a list of QrtrNode elements. The caller should not free the result, it is owned by `self` .

[transfer none][nullable][element-type QrtrNode]

Since: 1.0

### qrtr_bus_wait_for_node ()

    void
    qrtr_bus_wait_for_node (QrtrBus *self,
                            guint32 node_id,
                            guint timeout_ms,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously waits for the node with ID `node_id` .

When the operation is finished `callback` will be called. You can then call `qrtr_bus_wait_for_node_finish()` to get the result of the operation.

#### Parameters

self | a QrtrBus. |
node_id | the QRTR bus node ID to lookup. |
timeout_ms | the timeout, in milliseconds, to wait for the node to appear in the bus. |
cancellable | a GCancellable, or NULL. |
callback | a GAsyncReadyCallback to call when the request is satisfied. |
user_data | user data to pass to `callback` . |

Since: 1.0

### qrtr_bus_wait_for_node_finish ()

    QrtrNode *
    qrtr_bus_wait_for_node_finish (QrtrBus *self,
                                   GAsyncResult *res,
                                   GError **error);

Finishes an operation started with `qrtr_bus_wait_for_node()`.

#### Parameters

self | a QrtrBus. |
res | a GAsyncResult. |
error | Return location for error or `NULL`. |

#### Returns

A QrtrNode, or `NULL` if `error` is set.

[transfer full]

Since: 1.0

## Types and Values

### QRTR_BUS_LOOKUP_TIMEOUT

    #define QRTR_BUS_LOOKUP_TIMEOUT "lookup-timeout"

Symbol defining the “lookup-timeout” property.

Since: 1.0

### QRTR_BUS_SIGNAL_NODE_ADDED

    #define QRTR_BUS_SIGNAL_NODE_ADDED "node-added"

Symbol defining the “node-added” signal.

Since: 1.0

### QRTR_BUS_SIGNAL_NODE_REMOVED

    #define QRTR_BUS_SIGNAL_NODE_REMOVED "node-removed"

Symbol defining the “node-removed” signal.

Since: 1.0

### QrtrBus

    typedef struct _QrtrBus QrtrBus;

The QrtrBus structure contains private data and should only be accessed using the provided API.

Since: 1.0

## Property Details

### The `“lookup-timeout”` property

      “lookup-timeout”           guint

Timeout in ms to wait for the initial lookup to finish, or 0 to disable it.

Owner: QrtrBus

Flags: Read / Write / Construct Only

Default value: 0

Since: 1.0

## Signal Details

### The `“node-added”` signal

    void
    user_function (QrtrBus *self,
                   guint    node,
                   gpointer user_data)

The ::node-added signal is emitted when a new node registers a service on the QRTR bus.

#### Parameters

self | the QrtrBus |
node | the node ID of the node that has been added |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“node-removed”` signal

    void
    user_function (QrtrBus *self,
                   guint    node,
                   gpointer user_data)

The ::node-removed signal is emitted when a node deregisters all services from the QRTR bus.

#### Parameters

self | the QrtrBus |
node | the node ID of the node that was removed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0