External/libmks
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libmks.git synced 2024-12-22 13:45:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Document most of the public APIs

Browse Source
This commit is contained in:
Bilal Elmoussaoui 2023-05-23 12:24:33 +02:00
parent c0f0d1c22c
commit c7772df9aa
17 changed files with 337 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -1,7 +1,7 @@
# libmks
This library provides a "Mouse, Keyboard, and Screen" to Qemu using the
D-Bus device support in Qemu and GTK 4.
This library provides a "Mouse, Keyboard, and Screen" to QEMU using the
D-Bus device support in QEMU and GTK 4.
# Documentation
@ -9,9 +9,9 @@ Nightly documentation can be found [here](https://chergert.pages.gitlab.gnome.or
# Testing
By default, Qemu will connect to your user session D-Bus if you do not
By default, QEMU will connect to your user session D-Bus if you do not
provide an address for `-display dbus`. Therefore, it is pretty easy to
test things by running Qemu manually and then connecting with the test
test things by running QEMU manually and then connecting with the test
program `./tools/mks`.
```sh

2
docs/Mks.toml.in
View File

@ -6,7 +6,7 @@ website_url = "https://gitlab.gnome.org/chergert/libmks"
docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/"
authors = "Christian Hergert"
license = "LGPL-2.1-or-later"
description = "Mouse, Keyboard, and Screen to Qemu"
description = "Mouse, Keyboard, and Screen to QEMU"
dependencies = [ "GObject-2.0", "Gdk-4.0", "Gtk-4.0" ]
devhelp = true
search_index = true

2
lib/meson.build
View File

@ -138,7 +138,7 @@ libmks_dep = declare_dependency(
install_headers(libmks_headers, subdir: 'libmks-@0@'.format(api_version))
pkg.generate(
description: 'A shared library for Mouse, Keyboard, and Screen to Qemu',
description: 'A shared library for Mouse, Keyboard, and Screen to QEMU',
libraries: libmks,
name: 'libmks',
filebase: 'libmks-' + api_version,

17
lib/mks-device.c
View File

@ -23,6 +23,12 @@
#include "mks-device-private.h"
/**
* MksDevice:
*
* An abstraction of a virtualized QEMU device.
*/
G_DEFINE_TYPE (MksDevice, mks_device, G_TYPE_OBJECT)
enum {
@ -84,6 +90,11 @@ mks_device_class_init (MksDeviceClass *klass)
klass->setup = mks_device_real_setup;
/**
* MksDevice:name:
*
* The device name.
*/
properties [PROP_NAME] =
g_param_spec_string ("name", NULL, NULL,
NULL,
@ -97,6 +108,12 @@ mks_device_init (MksDevice *self)
{
}
/**
* mks_device_get_name:
* @self: A `MksDevice`
*
* Gets the device name.
*/
const char *
mks_device_get_name (MksDevice *self)
{

2
lib/mks-display-picture.c
View File

@ -347,7 +347,7 @@ mks_display_picture_legacy_event_cb (MksDisplayPicture *self,
/*
* Currently there is no touchpad D-Bus interface to communicate
* with Qemu. That is something we would very much want to have
* with QEMU. That is something we would very much want to have
* in the future so that we can do this properly.
*
* For now, we just "emulate" scroll events by looking at direction

24
lib/mks-init.c
View File

@ -41,7 +41,7 @@ mks_init_gtypes (void)
{
g_resources_register (mks_get_resource ());
/* First register GTypes for Qemu IPC */
/* First register GTypes for QEMU IPC */
g_type_ensure (MKS_QEMU_TYPE_AUDIO);
g_type_ensure (MKS_QEMU_TYPE_AUDIO_IN_LISTENER);
g_type_ensure (MKS_QEMU_TYPE_AUDIO_OUT_LISTENER);
@ -66,6 +66,13 @@ mks_init_gtypes (void)
g_type_ensure (MKS_TYPE_SESSION);
}
/**
* mks_init:
*
* Initializes the library.
*
* The function must be called before using any of the library functions.
*/
void
mks_init (void)
{
@ -86,18 +93,33 @@ _mks_init (void)
mks_init ();
}
/**
* mks_get_major_version:
*
* The major version the library.
*/
int
mks_get_major_version (void)
{
return MKS_MAJOR_VERSION;
}
/**
* mks_get_minor_version:
*
* The minor version the library.
*/
int
mks_get_minor_version (void)
{
return MKS_MINOR_VERSION;
}
/**
* mks_get_micro_version:
*
* The micro version the library.
*/
int
mks_get_micro_version (void)
{

68
lib/mks-keyboard.c
View File

@ -29,6 +29,12 @@
#include "mks-keymap-xorgevdev2qnum-private.h"
/**
* MksKeyboard:
*
* A virtualized QEMU keyboard.
*/
struct _MksKeyboard
{
MksDevice parent_instance;
@ -152,6 +158,11 @@ mks_keyboard_class_init (MksKeyboardClass *klass)
object_class->dispose = mks_keyboard_dispose;
object_class->get_property = mks_keyboard_get_property;
/**
* MksKeyboard:modifiers:
*
* Active keyboard modifiers.
*/
properties [PROP_MODIFIERS] =
g_param_spec_flags ("modifiers", NULL, NULL,
MKS_TYPE_KEYBOARD_MODIFIER,
@ -166,6 +177,12 @@ mks_keyboard_init (MksKeyboard *self)
{
}
/**
* mks_keyboard_get_modifiers:
* @self: an #MksKeyboard
*
* Get the active keyboard modifiers.
*/
MksKeyboardModifier
mks_keyboard_get_modifiers (MksKeyboard *self)
{
@ -221,7 +238,7 @@ mks_keyboard_press_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Asynchronously presses @keycode.
* Presses @keycode.
*/
void
mks_keyboard_press (MksKeyboard *self,
@ -253,6 +270,17 @@ mks_keyboard_press (MksKeyboard *self,
MKS_EXIT;
}
/**
* mks_keyboard_press_finish:
* @self: a `MksKeyboard`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Keyboard.press].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_keyboard_press_finish (MksKeyboard *self,
GAsyncResult *result,
@ -270,6 +298,19 @@ mks_keyboard_press_finish (MksKeyboard *self,
MKS_RETURN (ret);
}
/**
* mks_keyboard_press_sync:
* @self: an #MksKeyboard
* @keycode: the hardware keycode
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Synchronously press the `keycode`.
*
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean
mks_keyboard_press_sync (MksKeyboard *self,
guint keycode,
@ -322,7 +363,7 @@ mks_keyboard_release_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Asynchronously releases @keycode.
* Releases @keycode.
*/
void
mks_keyboard_release (MksKeyboard *self,
@ -354,6 +395,17 @@ mks_keyboard_release (MksKeyboard *self,
MKS_EXIT;
}
/**
* mks_keyboard_release_finish:
* @self: a `MksKeyboard`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Keyboard.release].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_keyboard_release_finish (MksKeyboard *self,
GAsyncResult *result,
@ -371,6 +423,18 @@ mks_keyboard_release_finish (MksKeyboard *self,
MKS_RETURN (ret);
}
/**
* mks_keyboard_release_sync:
* @self: an #MksKeyboard
* @keycode: the hardware keycode
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Synchronously release the `keycode`.
*
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean
mks_keyboard_release_sync (MksKeyboard *self,
guint keycode,

9
lib/mks-keyboard.h
View File

@ -42,6 +42,15 @@ G_BEGIN_DECLS
typedef struct _MksKeyboardClass MksKeyboardClass;
/**
* MksKeyboardModifier:
* @MKS_KEYBOARD_MODIFIER_NONE: No modifier.
* @MKS_KEYBOARD_MODIFIER_SCROLL_LOCK: Scroll lock.
* @MKS_KEYBOARD_MODIFIER_NUM_LOCK: Numeric lock.
* @MKS_KEYBOARD_MODIFIER_CAPS_LOCK: Caps lock.
*
* The active keyboard modifiers.
*/
typedef enum _MksKeyboardModifier
{
MKS_KEYBOARD_MODIFIER_NONE = 0,

95
lib/mks-mouse.c
View File

@ -25,6 +25,12 @@
#include "mks-mouse.h"
#include "mks-util-private.h"
/**
* MksMouse:
*
* A virtualized QEMU mouse.
*/
struct _MksMouse
{
MksDevice parent_instance;
@ -121,6 +127,11 @@ mks_mouse_class_init (MksMouseClass *klass)
device_class->setup = mks_mouse_setup;
/**
* MksMouse:is-absolute:
*
* Whether the mouse is using absolute movements.
*/
properties [PROP_IS_ABSOLUTE] =
g_param_spec_boolean ("is-absolute", NULL, NULL,
FALSE,
@ -134,6 +145,12 @@ mks_mouse_init (MksMouse *self)
{
}
/**
* mks_mouse_get_is_absolute:
* @self: A `MksMouse`.
*
* Whether the mouse is using absolute movements.
*/
gboolean
mks_mouse_get_is_absolute (MksMouse *self)
{
@ -224,6 +241,17 @@ mks_mouse_press (MksMouse *self,
MKS_EXIT;
}
/**
* mks_mouse_press_finish:
* @self: a `MksMouse`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Mouse.press].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_mouse_press_finish (MksMouse *self,
GAsyncResult *result,
@ -241,6 +269,18 @@ mks_mouse_press_finish (MksMouse *self,
MKS_RETURN (ret);
}
/**
* mks_mouse_press_sync:
* @self: an #MksMouse
* @button: the #MksMouseButton that was released
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Synchronously press a mouse button.
*
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean
mks_mouse_press_sync (MksMouse *self,
MksMouseButton button,
@ -288,7 +328,7 @@ mks_mouse_release_cb (GObject *object,
/**
* mks_mouse_release:
* @self: an #MksMouse
* @button: the #MksMouseButton that was releaseed
* @button: the #MksMouseButton that was released
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
@ -325,6 +365,17 @@ mks_mouse_release (MksMouse *self,
MKS_EXIT;
}
/**
* mks_mouse_release_finish:
* @self: a `MksMouse`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Mouse.release].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_mouse_release_finish (MksMouse *self,
GAsyncResult *result,
@ -342,6 +393,18 @@ mks_mouse_release_finish (MksMouse *self,
MKS_RETURN (ret);
}
/**
* mks_mouse_release_sync:
* @self: an #MksMouse
* @button: the #MksMouseButton that was released
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Synchronously releases a mouse button.
*
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean
mks_mouse_release_sync (MksMouse *self,
MksMouseButton button,
@ -431,6 +494,17 @@ mks_mouse_move_to (MksMouse *self,
MKS_EXIT;
}
/**
* mks_mouse_move_to_finish:
* @self: a `MksMouse`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Mouse.move_to].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_mouse_move_to_finish (MksMouse *self,
GAsyncResult *result,
@ -456,9 +530,9 @@ mks_mouse_move_to_finish (MksMouse *self,
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Moves to the absolute position at coordinates (x,y).
* Synchronously moves to the absolute position at coordinates (x,y).
*
* Returns: %TRUE if the operation was acknowledged by the Qemu instance;
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean
@ -554,6 +628,17 @@ mks_mouse_move_by (MksMouse *self,
MKS_EXIT;
}
/**
* mks_mouse_move_by_finish:
* @self: a `MksMouse`
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes a call to [method@Mks.Mouse.move_by].
*
* Returns: %TRUE if the operation completed successfully; otherwise %FALSE
* and @error is set.
*/
gboolean
mks_mouse_move_by_finish (MksMouse *self,
GAsyncResult *result,
@ -579,9 +664,9 @@ mks_mouse_move_by_finish (MksMouse *self,
* @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Moves the mouse by delta_x and delta_y.
* Synchronously moves the mouse by delta_x and delta_y.
*
* Returns: %TRUE if the operation was acknowledged by the Qemu instance;
* Returns: %TRUE if the operation was acknowledged by the QEMU instance;
* otherwise %FALSE and @error is set.
*/
gboolean

12
lib/mks-mouse.h
View File

@ -42,6 +42,18 @@ G_BEGIN_DECLS
typedef struct _MksMouseClass MksMouseClass;
/**
* MksMouseButton:
* @MKS_MOUSE_BUTTON_LEFT: Left button.
* @MKS_MOUSE_BUTTON_MIDDLE: Middle button.
* @MKS_MOUSE_BUTTON_RIGHT: Right button.
* @MKS_MOUSE_BUTTON_WHEEL_UP: Wheel-up button.
* @MKS_MOUSE_BUTTON_WHEEL_DOWN: Wheel-down button.
* @MKS_MOUSE_BUTTON_SIDE: Side button.
* @MKS_MOUSE_BUTTON_EXTRA: Extra button.
*
* A mouse button.
*/
typedef enum _MksMouseButton
{
MKS_MOUSE_BUTTON_LEFT = 0,

2
lib/mks-paintable.c
View File

@ -820,7 +820,7 @@ _mks_paintable_new (GCancellable *cancellable,
* _mks_paintable_get_cursor:
* @self: a #MksPaintable
*
* Gets the cursor as defined by the Qemu instance.
* Gets the cursor as defined by the QEMU instance.
*
* Returns: (transfer none) (nullable): a #GdkCursor or %NULL
*/

57
lib/mks-screen-attributes.c
View File

@ -23,6 +23,15 @@
#include "mks-screen-attributes-private.h"
/**
* MksScreenAttributes:
*
* Screen attributes.
*
* The attributes are used to reconfigure the QEMU instance with
* [method@Mks.Screen.configure] or [method@Mks.Screen.configure_sync].
*/
G_DEFINE_BOXED_TYPE (MksScreenAttributes,
mks_screen_attributes,
mks_screen_attributes_copy,
@ -63,8 +72,10 @@ mks_screen_attributes_copy (MksScreenAttributes *self)
* mks_screen_attributes_free:
* @self: a #MksScreenAttributes
*
* Frees a #MksScreenAttributes allocated using mks_screen_attributes_new()
* or mks_screen_attributes_copy().
* Frees a #MksScreenAttributes.
*
* Allocated using [ctor@Mks.ScreenAttributes.new]
* or [method@Mks.ScreenAttributes.copy].
*/
void
mks_screen_attributes_free (MksScreenAttributes *self)
@ -94,6 +105,13 @@ mks_screen_attributes_equal (MksScreenAttributes *self,
self->height_mm == other->height_mm);
}
/**
* mks_screen_attributes_set_width_mm:
* @self: A MksScreenAttributes.
* @width_mm: The screen width.
*
* Set the screen width in millimeters.
*/
void
mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
guint16 width_mm)
@ -101,6 +119,13 @@ mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
self->width_mm = width_mm;
}
/**
* mks_screen_attributes_set_height_mm:
* @self: A MksScreenAttributes.
* @height_mm: The screen height.
*
* Set the screen height in millimeters.
*/
void
mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
guint16 height_mm)
@ -108,6 +133,13 @@ mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
self->height_mm = height_mm;
}
/**
* mks_screen_attributes_set_x_offset:
* @self: A MksScreenAttributes.
* @x_offset: The screen's horizontal offset.
*
* Set the screen's horizontal offset in pixels.
*/
void
mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
int x_offset)
@ -115,6 +147,13 @@ mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
self->x_offset = x_offset;
}
/**
* mks_screen_attributes_set_y_offset:
* @self: A MksScreenAttributes.
* @y_offset: The screen's vertical offset.
*
* Set the screen's vertical offset in pixels.
*/
void
mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
int y_offset)
@ -122,6 +161,13 @@ mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
self->y_offset = y_offset;
}
/**
* mks_screen_attributes_set_width:
* @self: A MksScreenAttributes.
* @width: The screen width.
*
* Set the screen width in pixels.
*/
void
mks_screen_attributes_set_width (MksScreenAttributes *self,
guint width)
@ -129,6 +175,13 @@ mks_screen_attributes_set_width (MksScreenAttributes *self,
self->width = width;
}
/**
* mks_screen_attributes_set_height:
* @self: A MksScreenAttributes.
* @height: The screen height.
*
* Set the screen height in pixels.
*/
void
mks_screen_attributes_set_height (MksScreenAttributes *self,
guint height)

18
lib/mks-screen.c
View File

@ -478,11 +478,11 @@ mks_screen_configure_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Requests the Qemu instance reconfigure the screen with @attributes.
* Requests the QEMU instance reconfigure the screen with @attributes.
*
* This function takes ownership of @attributes.
*
* @callback is executed upon acknowledgment from the Qemu instance or
* @callback is executed upon acknowledgment from the QEMU instance or
* if the request timed out.
*
* Call mks_screen_configure_finish() to get the result.
@ -550,7 +550,7 @@ mks_screen_configure_finish (MksScreen *self,
* @cancellable: a #GCancellable
* @error: a location for a #GError, or %NULL
*
* Requests the Qemu instance reconfigure the screen using @attributes.
* Requests the QEMU instance reconfigure the screen using @attributes.
*
* This function takes ownership of @attributes.
*
@ -613,7 +613,7 @@ mks_screen_attach_cb (GObject *object,
* contents of the screen.
*
* This function registers a new `socketpair()` which is shared with
* the Qemu instance to receive rendering updates. Those updates are
* the QEMU instance to receive rendering updates. Those updates are
* propagated to the resulting #GdkPainable which can be retrieved
* using mks_screen_attach_finish() from @callback.
*/
@ -661,11 +661,11 @@ failure:
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
* Completes an asynchronous request to create a #GdkPaintable containing
* the contents of #MksScreen in the Qemu instance.
* Completes an asynchronous request to create a [iface@Gdk.Paintable] containing
* the contents of #MksScreen in the QEMU instance.
*
* The resulting #GdkPaintable will be updated as changes are delivered
* from Qemu over a private `socketpair()`. In the typical case, those
* The resulting [iface@Gdk.Paintable] will be updated as changes are delivered
* from QEMU over a private `socketpair()`. In the typical case, those
* changes are propagated using a DMA-BUF and damage notifications.
*
* Returns: (transfer full): a #GdkPainable if successful; otherwise %NULL
@ -689,7 +689,7 @@ mks_screen_attach_finish (MksScreen *self,
* @error: (nullable): a location for a #GError, or %NULL
*
* Synchronous request to attach to screen, creating a paintable that can
* be used to update display as the Qemu instance updates.
* be used to update display as the QEMU instance updates.
*
* Returns: (transfer full): a #GdkPaintable if successful; otherwise %NULL
* and @error is set.

7
lib/mks-screen.h
View File

@ -43,6 +43,13 @@ G_BEGIN_DECLS
typedef struct _MksScreenClass MksScreenClass;
/**
* MksScreenKind:
* @MKS_SCREEN_KIND_TEXT: A text only screen.
* @MKS_SCREEN_KIND_GRAPHIC: A graphical screen.
*
* A screen kind.
*/
typedef enum _MksScreenKind
{
MKS_SCREEN_KIND_TEXT = 0,

65
lib/mks-session.c
View File

@ -28,32 +28,32 @@
#include "mks-session.h"
/**
* SECTION:mks-session
* @Title: MksSession
* @Short_description: Session connected to a Qemu VM
* MksSession:
*
* The #MksSession represents a connection to a Qemu VM instance. It contains
* Session connected to a QEMU VM
*
* The `MksSession` represents a connection to a QEMU VM instance. It contains
* devices such as the mouse, keyboard, and screen which can be used with GTK.
*
* You may monitor #MksSession:devices using #GListModel:items-changed to be
* You may monitor [property@Mks.Session:devices] using [signal@Gio.ListModel::items-changed] to be
* notified of changes to available devices in the session.
*
* # Connecting To Qemu
* # Connecting To QEMU
*
* To use #MksSession, you should create your Qemu instance using `dbus` for
* To use `MksSession`, you should create your QEMU instance using `dbus` for
* the various devices that support it. You'll need to provide your P2P D-Bus
* address when connecting to Qemu.
* address when connecting to QEMU.
*
* Using the same #GDBusConnection, create a #MksSession with
* mks_session_new_for_connection(). The #MksSession instance will negotiate
* Using the same [class@Gio.DBusConnection], create a `MksSession` with
* [func@Mks.Session.new_for_connection]. The `MksSession` instance will negotiate
* with the peer to determine what devices are available and expose them
* via the #MksSession:devices #GListModel.
* via the [property@Mks.Session:devices] [iface@Gio.ListModel].
*
* # Creating Widgets
*
* You can create a new widget to embed in your application by waiting for
* a #MksScreen to become available in the list model or connecting to the
* #GObject::notify signal for the #MksSession:screen property.
* You can create a new widget to embed in your application by calling
* [method@Mks.Session.ref_screen] and set the screen for the [class@Mks.Display]
* with [method@Mks.Display.set_screen].
*/
static gboolean mks_session_initable_init (GInitable *initable,
@ -72,15 +72,15 @@ struct _MksSession
{
GObject parent_instance;
/* @connection is used to communicate with the Qemu instance. It is expected
/* @connection is used to communicate with the QEMU instance. It is expected
* to be a private point-to-point connection over a Unix socket, socketpair(),
* or other channel capable of passing FDs between peers.
*/
GDBusConnection *connection;
/* As devices are discovered from the Qemu instance, MksDevice-based objects
/* As devices are discovered from the QEMU instance, MksDevice-based objects
* are created for them and stored in @devices. Applications will work with
* these objects to perform operations on the Qemu instance. When we discover
* these objects to perform operations on the QEMU instance. When we discover
* the devices have been removed, we drop them from the listmodel.
*/
GListStore *devices;
@ -93,7 +93,7 @@ struct _MksSession
GListModel *devices_read_only;
/* An object manager client is used to monitor for new objects exported by
* the Qemu instance. Those objects are then wrapped by MksDevice objects
* the QEMU instance. Those objects are then wrapped by MksDevice objects
* as necessary and exported to consumers via @devices.
*/
GDBusObjectManager *object_manager;
@ -365,8 +365,7 @@ mks_session_class_init (MksSessionClass *klass)
/**
* MksSession:connection:
*
* The "connection" property contains the #GDBusConnection that is used
* to communicate with Qemu.
* The [class@Gio.DBusConnection] that is used to communicate with QEMU.
*/
properties [PROP_CONNECTION] =
g_param_spec_object ("connection", NULL, NULL,
@ -376,8 +375,8 @@ mks_session_class_init (MksSessionClass *klass)
/**
* MksSession:devices:
*
* The "devices" property contains a #GListModel of devices that have been
* discovered on the #GDBusConnection to Qemu.
* A [iface@Gio.ListModel] of devices that have been
* discovered on the [class@Gio.DBusConnection] to QEMU.
*/
properties [PROP_DEVICES] =
g_param_spec_object ("devices", NULL, NULL,
@ -387,8 +386,7 @@ mks_session_class_init (MksSessionClass *klass)
/**
* MksSession:name:
*
* The "name" property is the named of the VM as specified by the
* Qemu instance.
* The VM name as specified by the QEMU instance.
*/
properties [PROP_NAME] =
g_param_spec_string ("name", NULL, NULL,
@ -398,8 +396,7 @@ mks_session_class_init (MksSessionClass *klass)
/**
* MksSession:uuid:
*
* The "uuid" property is the unique identifier as specified by the
* Qemu instance for the VM.
* The VM unique identifier specified by the QEMU instance.
*/
properties [PROP_UUID] =
g_param_spec_string ("uuid", NULL, NULL,
@ -566,7 +563,7 @@ mks_session_new_for_connection_cb (GObject *object,
*
* Creates a #MksSession which communicates using @connection.
*
* The #GDBusConnection should be a private D-Bus connection to a Qemu
* The [class@Gio.DBusConnection] should be a private D-Bus connection to a QEMU
* instance which has devices created using the "dbus" backend.
* @callback will be executed when the session has been created or
@ -574,7 +571,7 @@ mks_session_new_for_connection_cb (GObject *object,
*
* This function will not block the calling thread.
*
* use mks_session_new_for_connection_finish() to get the result of
* use [ctor@Mks.Session.new_for_connection_finish] to get the result of
* this operation.
*/
void
@ -610,7 +607,7 @@ mks_session_new_for_connection (GDBusConnection *connection,
* @result: a #GAsyncResult provided to callback
* @error: (nullable): a location for a #GError or %NULL
*
* Completes a request to create a #MksSession for a #GDBusConnection.
* Completes a request to create a #MksSession for a [class@Gio.DBusConnection].
*
* Returns: (transfer full): a #MksSession if successful; otherwise %NULL
* and @error is set.
@ -626,13 +623,13 @@ mks_session_new_for_connection_finish (GAsyncResult *result,
/**
* mks_session_new_for_connection_sync:
* @connection: a private #GDBusConnetion to a Qemu instance
* @connection: a private #GDBusConnetion to a QEMU instance
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a location for a #GError, or %NULL
*
* Synchronously creates a new #MksSession instance.
*
* This may block while the Qemu instance is contacted to query for
* This may block while the QEMU instance is contacted to query for
* initial devices and VM status.
*
* Returns: (transfer full): a #MksSession if successful; otherwise %NULL
@ -661,7 +658,7 @@ mks_session_new_for_connection_sync (GDBusConnection *connection,
* mks_session_get_connection:
* @self: a #MksSession
*
* Gets the #MksSession:connection property.
* Gets the DBus connection used for this session.
*
* Returns: (transfer none) (nullable): a #GDBusConnection or %NULL if
* the connection has not been set, or was disposed.
@ -678,7 +675,7 @@ mks_session_get_connection (MksSession *self)
* mks_session_get_uuid:
* @self: a #MksSession
*
* Gets the "uuid" property.
* Gets the unique identifier of the VM.
*/
const char *
mks_session_get_uuid (MksSession *self)
@ -695,7 +692,7 @@ mks_session_get_uuid (MksSession *self)
* mks_session_get_name:
* @self: a #MksSession
*
* Gets the "name" property.
* Gets the name of the VM.
*/
const char *
mks_session_get_name (MksSession *self)

13
lib/mks-speaker.c
View File

@ -28,6 +28,12 @@
#include "mks-speaker.h"
#include "mks-util-private.h"
/**
* MksSpeaker:
*
* A virtualized QEMU speaker.
*/
struct _MksSpeaker
{
MksDevice parent_instance;
@ -310,9 +316,8 @@ mks_speaker_class_init (MksSpeakerClass *klass)
/**
* MksSpeaker:muted:
*
* The "muted" property denotes if audio received from the
* instance is dropped and the remote sound device should
* attempt to be set as muted.
* If audio received from the instance is dropped and
* the remote sound device should attempt to be set as muted.
*/
properties [PROP_MUTED] =
g_param_spec_boolean ("muted", NULL, NULL,
@ -348,7 +353,7 @@ mks_speaker_get_muted (MksSpeaker *self)
* @self: a #MksSpeaker
* @muted: if the speaker should be muted
*
* Sets the #MksSpeaker:muted property.
* Mute or un-mute the speaker.
*/
void
mks_speaker_set_muted (MksSpeaker *self,

2
tools/mks-connect.c
View File

@ -70,7 +70,7 @@ int
main (int argc,
char *argv[])
{
g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to Qemu at DBUS_ADDRESS");
g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to QEMU at DBUS_ADDRESS");
g_autoptr(GDBusConnection) connection = NULL;
g_autoptr(MksSession) session = NULL;
g_autoptr(GError) error = NULL;