diff options
| -rw-r--r-- | doc/reference/spice-gtk-docs.xml | 16 | ||||
| -rw-r--r-- | doc/reference/spice-gtk-sections.txt | 232 | ||||
| -rw-r--r-- | gtk/channel-cursor.c | 51 | ||||
| -rw-r--r-- | gtk/channel-cursor.h | 1 | ||||
| -rw-r--r-- | gtk/channel-display.c | 62 | ||||
| -rw-r--r-- | gtk/channel-display.h | 1 | ||||
| -rw-r--r-- | gtk/channel-inputs.c | 35 | ||||
| -rw-r--r-- | gtk/channel-inputs.h | 1 | ||||
| -rw-r--r-- | gtk/channel-main.c | 131 | ||||
| -rw-r--r-- | gtk/channel-main.h | 1 | ||||
| -rw-r--r-- | gtk/channel-playback.c | 43 | ||||
| -rw-r--r-- | gtk/channel-playback.h | 1 | ||||
| -rw-r--r-- | gtk/channel-record.c | 37 | ||||
| -rw-r--r-- | gtk/channel-record.h | 1 | ||||
| -rw-r--r-- | gtk/spice-audio.c | 24 | ||||
| -rw-r--r-- | gtk/spice-audio.h | 2 | ||||
| -rw-r--r-- | gtk/spice-channel.c | 46 | ||||
| -rw-r--r-- | gtk/spice-channel.h | 17 | ||||
| -rw-r--r-- | gtk/spice-grabsequence.h | 1 | ||||
| -rw-r--r-- | gtk/spice-session.c | 93 | ||||
| -rw-r--r-- | gtk/spice-session.h | 3 | ||||
| -rw-r--r-- | gtk/spice-util.c | 22 | ||||
| -rw-r--r-- | gtk/spice-widget.c | 11 | ||||
| -rw-r--r-- | gtk/spice-widget.h | 1 |
24 files changed, 782 insertions, 51 deletions
diff --git a/doc/reference/spice-gtk-docs.xml b/doc/reference/spice-gtk-docs.xml index 0057119..2938960 100644 --- a/doc/reference/spice-gtk-docs.xml +++ b/doc/reference/spice-gtk-docs.xml @@ -27,28 +27,26 @@ <title>Session and Channels Objects, from spice-client-glib</title> <xi:include href="xml/spice-session.xml"/> <xi:include href="xml/spice-channel.xml"/> + <xi:include href="xml/channel-cursor.xml"/> <xi:include href="xml/channel-display.xml"/> <xi:include href="xml/channel-inputs.xml"/> <xi:include href="xml/channel-main.xml"/> <xi:include href="xml/channel-playback.xml"/> <xi:include href="xml/channel-record.xml"/> - <xi:include href="xml/spice-channel-enums.xml"/> + </chapter> + + <chapter> + <title>GTK Widget, from spice-client-gtk</title> + <xi:include href="xml/spice-widget.xml"/> </chapter> <chapter id="application-support"> - <title>Application support, from spice-client-glib</title> + <title>Application Support, from spice-client-glib</title> <xi:include href="xml/spice-audio.xml"/> - <xi:include href="xml/spice-cmdline.xml"/> <xi:include href="xml/spice-util.xml"/> </chapter> - <chapter> - <title>Display GTK Widget, from spice-client-gtk</title> - <xi:include href="xml/spice-widget.xml"/> - <xi:include href="xml/spice-widget-enums.xml"/> - <xi:include href="xml/spice-grabsequence.xml"/> - </chapter> </part> <chapter id="object-tree"> diff --git a/doc/reference/spice-gtk-sections.txt b/doc/reference/spice-gtk-sections.txt new file mode 100644 index 0000000..c7f1709 --- /dev/null +++ b/doc/reference/spice-gtk-sections.txt @@ -0,0 +1,232 @@ +<SECTION> +<FILE>channel-playback</FILE> +<TITLE>SpicePlaybackChannel</TITLE> +SpicePlaybackChannel +SpicePlaybackChannelClass +<SUBSECTION Standard> +SPICE_PLAYBACK_CHANNEL +SPICE_IS_PLAYBACK_CHANNEL +SPICE_TYPE_PLAYBACK_CHANNEL +spice_playback_channel_get_type +SPICE_PLAYBACK_CHANNEL_CLASS +SPICE_IS_PLAYBACK_CHANNEL_CLASS +SPICE_PLAYBACK_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_playback_channel +</SECTION> + +<SECTION> +<FILE>spice-session</FILE> +<TITLE>SpiceSession</TITLE> +SpiceSession +SpiceSessionClass +spice_session_new +spice_session_connect +spice_session_open_fd +spice_session_disconnect +spice_session_get_channels +<SUBSECTION> +spice_cmdline_get_option_group +spice_cmdline_session_setup +<SUBSECTION Standard> +SPICE_SESSION +SPICE_IS_SESSION +SPICE_TYPE_SESSION +spice_session_get_type +SPICE_SESSION_CLASS +SPICE_IS_SESSION_CLASS +SPICE_SESSION_GET_CLASS +</SECTION> + +<SECTION> +<FILE>channel-main</FILE> +<TITLE>SpiceMainChannel</TITLE> +SpiceMainChannel +SpiceMainChannelClass +spice_main_channel +spice_main_set_display +spice_main_clipboard_grab +spice_main_clipboard_release +spice_main_clipboard_notify +spice_main_clipboard_request +<SUBSECTION Standard> +SPICE_MAIN_CHANNEL +SPICE_IS_MAIN_CHANNEL +SPICE_TYPE_MAIN_CHANNEL +spice_main_channel_get_type +SPICE_MAIN_CHANNEL_CLASS +SPICE_IS_MAIN_CHANNEL_CLASS +SPICE_MAIN_CHANNEL_GET_CLASS +</SECTION> + +<SECTION> +<FILE>spice-channel</FILE> +<TITLE>SpiceChannel</TITLE> +SpiceChannelEvent +SpiceChannel +SpiceChannelClass +spice_channel_new +spice_channel_destroy +spice_channel_connect +spice_channel_open_fd +spice_channel_disconnect +spice_channel_test_capability +spice_channel_set_capability +<SUBSECTION Standard> +SPICE_TYPE_CHANNEL_EVENT +spice_channel_event_get_type +SPICE_CHANNEL +SPICE_IS_CHANNEL +SPICE_TYPE_CHANNEL +spice_channel_get_type +SPICE_CHANNEL_CLASS +SPICE_IS_CHANNEL_CLASS +SPICE_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_msg_handler +spice_msg_in +spice_msg_out +</SECTION> + +<SECTION> +<FILE>spice-audio</FILE> +<TITLE>SpiceAudio</TITLE> +SpiceAudio +SpiceAudioClass +spice_audio_new +<SUBSECTION Standard> +SPICE_AUDIO +SPICE_IS_AUDIO +SPICE_TYPE_AUDIO +spice_audio_get_type +SPICE_AUDIO_CLASS +SPICE_IS_AUDIO_CLASS +SPICE_AUDIO_GET_CLASS +</SECTION> + +<SECTION> +<FILE>channel-display</FILE> +<TITLE>SpiceDisplayChannel</TITLE> +SpiceDisplayChannel +SpiceDisplayChannelClass +<SUBSECTION Standard> +SPICE_DISPLAY_CHANNEL +SPICE_IS_DISPLAY_CHANNEL +SPICE_TYPE_DISPLAY_CHANNEL +spice_display_channel_get_type +SPICE_DISPLAY_CHANNEL_CLASS +SPICE_IS_DISPLAY_CHANNEL_CLASS +SPICE_DISPLAY_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_display_channel +</SECTION> + +<SECTION> +<FILE>channel-cursor</FILE> +<TITLE>SpiceCursorChannel</TITLE> +SpiceCursorChannel +SpiceCursorChannelClass +<SUBSECTION Standard> +SPICE_CURSOR_CHANNEL +SPICE_IS_CURSOR_CHANNEL +SPICE_TYPE_CURSOR_CHANNEL +spice_cursor_channel_get_type +SPICE_CURSOR_CHANNEL_CLASS +SPICE_IS_CURSOR_CHANNEL_CLASS +SPICE_CURSOR_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_cursor_channel +</SECTION> + +<SECTION> +<FILE>channel-record</FILE> +<TITLE>SpiceRecordChannel</TITLE> +SpiceRecordChannel +SpiceRecordChannelClass +spice_record_send_data +<SUBSECTION Standard> +SPICE_RECORD_CHANNEL +SPICE_IS_RECORD_CHANNEL +SPICE_TYPE_RECORD_CHANNEL +spice_record_channel_get_type +SPICE_RECORD_CHANNEL_CLASS +SPICE_IS_RECORD_CHANNEL_CLASS +SPICE_RECORD_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_record_channel +</SECTION> + +<SECTION> +<FILE>channel-inputs</FILE> +<TITLE>SpiceInputsChannel</TITLE> +SpiceInputsChannel +SpiceInputsChannelClass +SpiceInputsLock +spice_inputs_motion +spice_inputs_position +spice_inputs_button_press +spice_inputs_button_release +spice_inputs_key_press +spice_inputs_key_release +spice_inputs_set_key_locks +<SUBSECTION Standard> +SPICE_TYPE_INPUTS_LOCK +spice_inputs_lock_get_type +SPICE_INPUTS_CHANNEL +SPICE_IS_INPUTS_CHANNEL +SPICE_TYPE_INPUTS_CHANNEL +spice_inputs_channel_get_type +SPICE_INPUTS_CHANNEL_CLASS +SPICE_IS_INPUTS_CHANNEL_CLASS +SPICE_INPUTS_CHANNEL_GET_CLASS +<SUBSECTION Private> +spice_inputs_channel +</SECTION> + +<SECTION> +<FILE>spice-widget</FILE> +<TITLE>SpiceDisplay</TITLE> +SpiceDisplay +SpiceDisplayClass +SpiceDisplayKeyEvent +spice_display_new +spice_display_mouse_ungrab +spice_display_copy_to_guest +spice_display_paste_from_guest +spice_display_set_grab_keys +spice_display_get_grab_keys +spice_display_send_keys +spice_display_get_pixbuf +<SUBSECTION> +SpiceGrabSequence +spice_grab_sequence_new +spice_grab_sequence_new_from_string +spice_grab_sequence_copy +spice_grab_sequence_free +spice_grab_sequence_as_string +<SUBSECTION Standard> +SPICE_DISPLAY +SPICE_IS_DISPLAY +SPICE_TYPE_DISPLAY +spice_display_get_type +SPICE_DISPLAY_CLASS +SPICE_IS_DISPLAY_CLASS +SPICE_DISPLAY_GET_CLASS +SPICE_TYPE_GRAB_SEQUENCE +spice_grab_sequence_get_type +SPICE_TYPE_DISPLAY_KEY_EVENT +spice_display_key_event_get_type +<SUBSECTION Private> +spice_display +</SECTION> + +<SECTION> +<FILE>spice-util</FILE> +spice_util_set_debug +spice_util_get_version_string +<SUBSECTION Private> +SPICE_DEBUG +spice_util_get_debug +SPICE_RESERVED_PADDING +</SECTION> + diff --git a/gtk/channel-cursor.c b/gtk/channel-cursor.c index a2f861f..76bb0d0 100644 --- a/gtk/channel-cursor.c +++ b/gtk/channel-cursor.c @@ -22,6 +22,22 @@ #include "spice-channel-cache.h" #include "spice-marshal.h" +/** + * SECTION:channel-cursor + * @short_description: update cursor shape and position + * @title: Cursor Channel + * @section_id: + * @see_also: #SpiceChannel, and the GTK widget #SpiceDisplay + * @stability: Stable + * @include: channel-cursor.h + * + * The Spice protocol defines a set of messages for controlling cursor + * shape and position on the remote display area. The cursor changes + * that should be reflected on the display are notified by + * signals. See for example #SpiceCursorChannel::cursor-set + * #SpiceCursorChannel::cursor-move signals. + */ + #define SPICE_CURSOR_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_CURSOR_CHANNEL, spice_cursor_channel)) @@ -79,6 +95,18 @@ static void spice_cursor_channel_class_init(SpiceCursorChannelClass *klass) gobject_class->finalize = spice_cursor_channel_finalize; channel_class->handle_msg = spice_cursor_handle_msg; + /** + * SpiceCursorChannel::cursor-set: + * @cursor: the #SpiceCursorChannel that emitted the signal + * @width: width of the shape + * @height: height of the shape + * @hot_x: position of hot spot on x axis + * @hot_y: position of hot spot on y axis + * @rgba: shape data + * + * The #SpiceCursorChannel::cursor-set signal is emitted to modify + * cursor aspect and position on the display area. + **/ signals[SPICE_CURSOR_SET] = g_signal_new("cursor-set", G_OBJECT_CLASS_TYPE(gobject_class), @@ -92,6 +120,15 @@ static void spice_cursor_channel_class_init(SpiceCursorChannelClass *klass) G_TYPE_INT, G_TYPE_INT, G_TYPE_POINTER); + /** + * SpiceCursorChannel::cursor-move: + * @cursor: the #SpiceCursorChannel that emitted the signal + * @x: x position + * @y: y position + * + * The #SpiceCursorChannel::cursor-move signal is emitted to update + * the cursor position on the display area. + **/ signals[SPICE_CURSOR_MOVE] = g_signal_new("cursor-move", G_OBJECT_CLASS_TYPE(gobject_class), @@ -103,6 +140,13 @@ static void spice_cursor_channel_class_init(SpiceCursorChannelClass *klass) 2, G_TYPE_INT, G_TYPE_INT); + /** + * SpiceCursorChannel::cursor-hide: + * @cursor: the #SpiceCursorChannel that emitted the signal + * + * The #SpiceCursorChannel::cursor-hide signal is emitted to hide + * the cursor/pointer on the display area. + **/ signals[SPICE_CURSOR_HIDE] = g_signal_new("cursor-hide", G_OBJECT_CLASS_TYPE(gobject_class), @@ -113,6 +157,13 @@ static void spice_cursor_channel_class_init(SpiceCursorChannelClass *klass) G_TYPE_NONE, 0); + /** + * SpiceCursorChannel::cursor-reset: + * @cursor: the #SpiceCursorChannel that emitted the signal + * + * The #SpiceCursorChannel::cursor-reset signal is emitted to + * reset the cursor to its default context. + **/ signals[SPICE_CURSOR_RESET] = g_signal_new("cursor-reset", G_OBJECT_CLASS_TYPE(gobject_class), diff --git a/gtk/channel-cursor.h b/gtk/channel-cursor.h index 92005ed..9983694 100644 --- a/gtk/channel-cursor.h +++ b/gtk/channel-cursor.h @@ -49,6 +49,7 @@ struct _SpiceCursorChannelClass { void (*cursor_hide)(SpiceCursorChannel *channel); void (*cursor_reset)(SpiceCursorChannel *channel); + /*< private >*/ /* Do not add fields to this struct */ }; diff --git a/gtk/channel-display.c b/gtk/channel-display.c index dacfc5e..70ec0f3 100644 --- a/gtk/channel-display.c +++ b/gtk/channel-display.c @@ -27,6 +27,25 @@ #include <sys/ipc.h> #include <sys/shm.h> +/** + * SECTION:channel-display + * @short_description: remote display area + * @title: Display Channel + * @section_id: + * @see_also: #SpiceChannel, and the GTK widget #SpiceDisplay + * @stability: Stable + * @include: channel-display.h + * + * A class that handles the rendering of the remote display and inform + * of its updates. + * + * The creation of the main graphic buffer is signaled with + * #SpiceDisplayChannel::display-primary-create. + * + * The update of regions is notified by + * #SpiceDisplayChannel::display-invalidate signals. + */ + #define SPICE_DISPLAY_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_DISPLAY_CHANNEL, spice_display_channel)) @@ -89,6 +108,20 @@ static void spice_display_channel_class_init(SpiceDisplayChannelClass *klass) channel_class->handle_msg = spice_display_handle_msg; channel_class->channel_up = spice_display_channel_up; + /** + * SpiceDisplayChannel::display-primary-create: + * @display: the #SpiceDisplayChannel that emitted the signal + * @format: %SPICE_SURFACE_FMT_32_xRGB or %SPICE_SURFACE_FMT_16_555; + * @width: width resolution + * @height: height resolution + * @stride: the buffer stride ("width" padding) + * @shmid: identifier of the shared memory segment associated with + * the @imgdata, or -1 if not shm + * @imgdata: pointer to surface buffer + * + * The #SpiceDisplayChannel::display-primary-create signal + * provides main display buffer data. + **/ signals[SPICE_DISPLAY_PRIMARY_CREATE] = g_signal_new("display-primary-create", G_OBJECT_CLASS_TYPE(gobject_class), @@ -102,6 +135,14 @@ static void spice_display_channel_class_init(SpiceDisplayChannelClass *klass) G_TYPE_INT, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT, G_TYPE_POINTER); + /** + * SpiceDisplayChannel::display-primary-destroy: + * @display: the #SpiceDisplayChannel that emitted the signal + * + * The #SpiceDisplayChannel::display-primary-destroy signal is + * emitted when the primary surface is freed and should not be + * accessed anymore. + **/ signals[SPICE_DISPLAY_PRIMARY_DESTROY] = g_signal_new("display-primary-destroy", G_OBJECT_CLASS_TYPE(gobject_class), @@ -113,6 +154,18 @@ static void spice_display_channel_class_init(SpiceDisplayChannelClass *klass) G_TYPE_NONE, 0); + /** + * SpiceDisplayChannel::display-invalidate: + * @display: the #SpiceDisplayChannel that emitted the signal + * @x: x position + * @y: y position + * @width: width + * @height: height + * + * The #SpiceDisplayChannel::display-invalidate signal is emitted + * when the rectangular region x/y/w/h of the primary buffer is + * updated. + **/ signals[SPICE_DISPLAY_INVALIDATE] = g_signal_new("display-invalidate", G_OBJECT_CLASS_TYPE(gobject_class), @@ -125,6 +178,14 @@ static void spice_display_channel_class_init(SpiceDisplayChannelClass *klass) 4, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT); + /** + * SpiceDisplayChannel::display-mark: + * @display: the #SpiceDisplayChannel that emitted the signal + * + * The #SpiceDisplayChannel::display-mark signal is emitted when + * the %RED_DISPLAY_MARK command is received, and the display + * should be exposed. + **/ signals[SPICE_DISPLAY_MARK] = g_signal_new("display-mark", G_OBJECT_CLASS_TYPE(gobject_class), @@ -1015,4 +1076,3 @@ static void spice_display_handle_msg(SpiceChannel *channel, spice_msg_in *msg) g_return_if_fail(display_handlers[type] != NULL); display_handlers[type](channel, msg); } - diff --git a/gtk/channel-display.h b/gtk/channel-display.h index 90cefd8..da61efa 100644 --- a/gtk/channel-display.h +++ b/gtk/channel-display.h @@ -52,6 +52,7 @@ struct _SpiceDisplayChannelClass { void (*display_mark)(SpiceChannel *channel, gboolean mark); + /*< private >*/ /* Do not add fields to this struct */ }; diff --git a/gtk/channel-inputs.c b/gtk/channel-inputs.c index 858b229..5dc9c03 100644 --- a/gtk/channel-inputs.c +++ b/gtk/channel-inputs.c @@ -19,6 +19,25 @@ #include "spice-common.h" #include "spice-channel-priv.h" +/** + * SECTION:channel-inputs + * @short_description: control the server mouse and keyboard + * @title: Inputs Channel + * @section_id: + * @see_also: #SpiceChannel, and the GTK widget #SpiceDisplay + * @stability: Stable + * @include: channel-inputs.h + * + * Spice supports sending keyboard key events and keyboard leds + * synchronization. The key events are sent using + * spice_inputs_key_press() and spice_inputs_key_release() using PC AT + * scancode. + * + * Guest keyboard leds state can be manipulated with + * spice_inputs_set_key_locks(). When key lock change, a notification + * is emitted with #SpiceInputsChannel::inputs-modifiers signal. + */ + #define SPICE_INPUTS_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_INPUTS_CHANNEL, spice_inputs_channel)) @@ -98,13 +117,21 @@ static void spice_inputs_channel_class_init(SpiceInputsChannelClass *klass) (gobject_class, PROP_KEY_MODIFIERS, g_param_spec_int("key-modifiers", "Key modifiers", - "Guest keyboard modifier state (derived from kbd leds)", + "Guest keyboard lock/led state", 0, INT_MAX, 0, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * SpiceInputsChannel::inputs-modifier: + * @display: the #SpiceInputsChannel that emitted the signal + * + * The #SpiceInputsChannel::inputs-modifier signal is emitted when + * the guest keyboard locks are changed. You can read the current + * state from #SpiceInputsChannel:key-modifiers property. + **/ /* TODO: use notify instead? */ signals[SPICE_INPUTS_MODIFIERS] = g_signal_new("inputs-modifiers", @@ -439,7 +466,7 @@ void spice_inputs_button_release(SpiceInputsChannel *channel, gint button, /** * spice_inputs_key_press: * @channel: - * @scancode: key scancode + * @scancode: a PC AT key scancode * * Press a key. **/ @@ -468,7 +495,7 @@ void spice_inputs_key_press(SpiceInputsChannel *channel, guint scancode) /** * spice_inputs_key_release: * @channel: - * @scancode: key scancode + * @scancode: a PC AT key scancode * * Release a key. **/ @@ -521,7 +548,7 @@ static spice_msg_out* set_key_locks(SpiceInputsChannel *channel, guint locks) /** * spice_inputs_set_key_locks: * @channel: - * @locks: SPICE_INPUTS_*_LOCK modifiers flags + * @locks: #SpiceInputsLock modifiers flags * * Set the keyboard locks on the guest (Caps, Num, Scroll..) **/ diff --git a/gtk/channel-inputs.h b/gtk/channel-inputs.h index ac96af5..c2f1f1d 100644 --- a/gtk/channel-inputs.h +++ b/gtk/channel-inputs.h @@ -51,6 +51,7 @@ struct _SpiceInputsChannelClass { /* signals */ void (*inputs_modifiers)(SpiceChannel *channel); + /*< private >*/ /* Do not add fields to this struct */ }; diff --git a/gtk/channel-main.c b/gtk/channel-main.c index 3024756..9034a8f 100644 --- a/gtk/channel-main.c +++ b/gtk/channel-main.c @@ -24,6 +24,22 @@ #include <spice/vd_agent.h> +/** + * SECTION:channel-main + * @short_description: the main Spice channel + * @title: Main Channel + * @section_id: + * @see_also: #SpiceChannel, and the GTK widget #SpiceDisplay + * @stability: Stable + * @include: channel-main.h + * + * The main channel is the Spice session control channel. It handles + * communication initialization (channels list), migrations, mouse + * modes, multimedia time, and agent communication. + * + * + */ + #define SPICE_MAIN_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_MAIN_CHANNEL, spice_main_channel)) @@ -222,11 +238,22 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) channel_class->handle_msg = spice_main_handle_msg; channel_class->iterate_write = spice_channel_iterate_write; + /** + * SpiceMainChannel:mouse-mode: + * + * Spice protocol specifies two mouse modes, client mode and + * server mode. In client mode (%SPICE_MOUSE_MODE_CLIENT), the + * affective mouse is the client side mouse: the client sends + * mouse position within the display and the server sends mouse + * shape messages. In server mode (%SPICE_MOUSE_MODE_SERVER), the + * client sends relative mouse movements and the server sends + * position and shape commands. + **/ g_object_class_install_property (gobject_class, PROP_MOUSE_MODE, g_param_spec_int("mouse-mode", "Mouse mode", - "", + "Mouse mode", 0, INT_MAX, 0, G_PARAM_READABLE | G_PARAM_STATIC_NAME | @@ -237,7 +264,7 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) (gobject_class, PROP_AGENT_CONNECTED, g_param_spec_boolean("agent-connected", "Agent connected", - "", + "Whether the agent is connected", FALSE, G_PARAM_READABLE | G_PARAM_STATIC_NAME | @@ -257,27 +284,30 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) g_object_class_install_property (gobject_class, PROP_DISPLAY_DISABLE_WALLPAPER, - g_param_spec_boolean("display-disable-wallpaper", - "Disable wallpaper", - "", FALSE, + g_param_spec_boolean("disable-wallpaper", + "Disable guest wallpaper", + "Disable guest wallpaper", + FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (gobject_class, PROP_DISPLAY_DISABLE_FONT_SMOOTH, - g_param_spec_boolean("display-disable-font-smooth", - "Disable font smooth", - "", FALSE, + g_param_spec_boolean("disable-font-smooth", + "Disable guest font smooth", + "Disable guest font smoothing", + FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (gobject_class, PROP_DISPLAY_DISABLE_ANIMATION, - g_param_spec_boolean("display-disable-animation", - "Disable animations", - "", FALSE, + g_param_spec_boolean("disable-animation", + "Disable guest animations", + "Disable guest animations", + FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); @@ -285,8 +315,8 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) g_object_class_install_property (gobject_class, PROP_DISPLAY_SET_COLOR_DEPTH, g_param_spec_boolean("set-color-depth", - "Set color depth", - "", FALSE, + "set color depth", + "Set display color depth", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); @@ -295,11 +325,18 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) (gobject_class, PROP_DISPLAY_COLOR_DEPTH, g_param_spec_uint("color-depth", "Color depth", - "", 8, 32, 32, + "Color depth", 8, 32, 32, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); + /* TODO use notify instead */ + /** + * SpiceMainChannel::main-mouse-update: + * @main: the #SpiceMainChannel that emitted the signal + * + * Notify when the mouse mode has changed. + **/ signals[SPICE_MAIN_MOUSE_UPDATE] = g_signal_new("main-mouse-update", G_OBJECT_CLASS_TYPE(gobject_class), @@ -310,6 +347,14 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) G_TYPE_NONE, 0); + /* TODO use notify instead */ + /** + * SpiceMainChannel::main-clipboard: + * @main: the #SpiceMainChannel that emitted the signal + * + * Notify when the %SpiceMainChannel:agent-connected or + * %SpiceMainChannel:agent-caps-0 property change. + **/ signals[SPICE_MAIN_AGENT_UPDATE] = g_signal_new("main-agent-update", G_OBJECT_CLASS_TYPE(gobject_class), @@ -319,7 +364,15 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * SpiceMainChannel::main-clipboard: + * @main: the #SpiceMainChannel that emitted the signal + * @type: the VD_AGENT_CLIPBOARD data type + * @data: clipboard data + * @size: size of @data in bytes + * + * Provides guest clipboard data requested by spice_main_clipboard_request(). + **/ signals[SPICE_MAIN_CLIPBOARD] = g_signal_new("main-clipboard", G_OBJECT_CLASS_TYPE(gobject_class), @@ -331,6 +384,15 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) 3, G_TYPE_UINT, G_TYPE_POINTER, G_TYPE_UINT); + /** + * SpiceMainChannel::main-clipboard-grab: + * @main: the #SpiceMainChannel that emitted the signal + * @types: the VD_AGENT_CLIPBOARD data types + * @ntypes: the number of @types + * + * Inform when clipboard data is available from the guest, and for + * which @types. + **/ signals[SPICE_MAIN_CLIPBOARD_GRAB] = g_signal_new("main-clipboard-grab", G_OBJECT_CLASS_TYPE(gobject_class), @@ -342,6 +404,15 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) 2, G_TYPE_POINTER, G_TYPE_UINT); + /** + * SpiceMainChannel::main-clipboard-request: + * @main: the #SpiceMainChannel that emitted the signal + * @types: the VD_AGENT_CLIPBOARD request type + * Returns: %TRUE if the request is successful + * + * Request clipbard data from the client. + * + **/ signals[SPICE_MAIN_CLIPBOARD_REQUEST] = g_signal_new("main-clipboard-request", G_OBJECT_CLASS_TYPE(gobject_class), @@ -353,6 +424,14 @@ static void spice_main_channel_class_init(SpiceMainChannelClass *klass) 1, G_TYPE_UINT); + /** + * SpiceMainChannel::main-clipboard-release: + * @main: the #SpiceMainChannel that emitted the signal + * + * Inform when the clipboard is released from the guest, when no + * clipboard data is available from the guest. + * + **/ signals[SPICE_MAIN_CLIPBOARD_RELEASE] = g_signal_new("main-clipboard-release", G_OBJECT_CLASS_TYPE(gobject_class), @@ -1000,9 +1079,9 @@ static gboolean timer_set_display(gpointer data) /** * spice_main_set_display: * @channel: - * @id: TODO: display channel id? or monitor id? - * @x: .. - * @y: .. + * @id: display channel ID + * @x: x position + * @y: y position * @width: display width * @height: display height * @@ -1034,10 +1113,10 @@ void spice_main_set_display(SpiceMainChannel *channel, int id, /** * spice_main_clipboard_grab: * @channel: - * @types: an array of #VD_AGENT_CLIPBOARD types - * @ntypes: the number of types in @types + * @types: an array of #VD_AGENT_CLIPBOARD types available in the clipboard + * @ntypes: the number of @types * - * Grab the guest clipboard for #VD_AGENT_CLIPBOARD @types. + * Grab the guest clipboard, with #VD_AGENT_CLIPBOARD @types. **/ void spice_main_clipboard_grab(SpiceMainChannel *channel, guint32 *types, int ntypes) { @@ -1051,8 +1130,8 @@ void spice_main_clipboard_grab(SpiceMainChannel *channel, guint32 *types, int nt * spice_main_clipboard_release: * @channel: * - * Release clipboard, when client loose clipboard, inform guest no - * clipboard data is available. + * Release the clipboard (for example, when the client looses the + * clipboard grab): Inform the guest no clipboard data is available. **/ void spice_main_clipboard_release(SpiceMainChannel *channel) { @@ -1069,7 +1148,7 @@ void spice_main_clipboard_release(SpiceMainChannel *channel) * @data: clipboard data * @size: data length in bytes * - * Send clipboard data to guest. + * Send the clipboard data to the guest. **/ void spice_main_clipboard_notify(SpiceMainChannel *channel, guint32 type, const guchar *data, size_t size) @@ -1085,8 +1164,8 @@ void spice_main_clipboard_notify(SpiceMainChannel *channel, * @channel: * @type: a #VD_AGENT_CLIPBOARD type * - * Request clipboard data of @type from guest. The reply is sent - * through ::main-clipboard signal. + * Request clipboard data of @type from the guest. The reply is sent + * through the #SpiceMainChannel::main-clipboard signal. **/ void spice_main_clipboard_request(SpiceMainChannel *channel, guint32 type) { diff --git a/gtk/channel-main.h b/gtk/channel-main.h index bc30d26..9a4f884 100644 --- a/gtk/channel-main.h +++ b/gtk/channel-main.h @@ -46,6 +46,7 @@ struct _SpiceMainChannelClass { void (*mouse_update)(SpiceChannel *channel); void (*agent_update)(SpiceChannel *channel); + /*< private >*/ /* Do not add fields to this struct */ }; diff --git a/gtk/channel-playback.c b/gtk/channel-playback.c index 6fae6c1..d08679e 100644 --- a/gtk/channel-playback.c +++ b/gtk/channel-playback.c @@ -23,6 +23,25 @@ #include "spice-marshal.h" +/** + * SECTION:channel-playback + * @short_description: audio stream for playback + * @title: Playback Channel + * @section_id: + * @see_also: #SpiceChannel, and #SpiceAudio + * @stability: Stable + * @include: channel-playback.h + * + * #SpicePlaybackChannel class handles an audio playback stream. The + * audio data is received via #SpicePlaybackChannel::playback-data + * signal, and is controlled by the guest with + * #SpicePlaybackChannel::playback-stop and + * #SpicePlaybackChannel::playback-start signal events. + * + * Note: You may be interested to let the #SpiceAudio class play and + * record audio channels for your application. + */ + #define SPICE_PLAYBACK_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_PLAYBACK_CHANNEL, spice_playback_channel)) @@ -83,6 +102,16 @@ static void spice_playback_channel_class_init(SpicePlaybackChannelClass *klass) gobject_class->finalize = spice_playback_channel_finalize; channel_class->handle_msg = spice_playback_handle_msg; + /** + * SpicePlaybackChannel::playback-start: + * @channel: the #SpicePlaybackChannel that emitted the signal + * @format: a #SPICE_AUDIO_FMT + * @channels: number of channels + * @rate: audio rate + * + * Notify when the playback should start, and provide audio format + * characteristics. + **/ signals[SPICE_PLAYBACK_START] = g_signal_new("playback-start", G_OBJECT_CLASS_TYPE(gobject_class), @@ -94,6 +123,14 @@ static void spice_playback_channel_class_init(SpicePlaybackChannelClass *klass) 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT); + /** + * SpicePlaybackChannel::playback-data: + * @channel: the #SpicePlaybackChannel that emitted the signal + * @data: pointer to audio data + * @data_size: size in byte of @data + * + * Provide audio data to be played. + **/ signals[SPICE_PLAYBACK_DATA] = g_signal_new("playback-data", G_OBJECT_CLASS_TYPE(gobject_class), @@ -105,6 +142,12 @@ static void spice_playback_channel_class_init(SpicePlaybackChannelClass *klass) 2, G_TYPE_POINTER, G_TYPE_INT); + /** + * SpicePlaybackChannel::playback-stop: + * @channel: the #SpicePlaybackChannel that emitted the signal + * + * Notify when the playback should stop. + **/ signals[SPICE_PLAYBACK_STOP] = g_signal_new("playback-stop", G_OBJECT_CLASS_TYPE(gobject_class), diff --git a/gtk/channel-playback.h b/gtk/channel-playback.h index d7f952c..6b62194 100644 --- a/gtk/channel-playback.h +++ b/gtk/channel-playback.h @@ -48,6 +48,7 @@ struct _SpicePlaybackChannelClass { void (*playback_data)(SpicePlaybackChannel *channel, gpointer *data, gint size); void (*playback_stop)(SpicePlaybackChannel *channel); + /*< private >*/ /* * If adding fields to this struct, remove corresponding * amount of padding to avoid changing overall struct size diff --git a/gtk/channel-record.c b/gtk/channel-record.c index df9e8a5..382ff40 100644 --- a/gtk/channel-record.c +++ b/gtk/channel-record.c @@ -24,6 +24,27 @@ #include "spice-marshal.h" #include "spice-session-priv.h" +/** + * SECTION:channel-record + * @short_description: audio stream for recording + * @title: Record Channel + * @section_id: + * @see_also: #SpiceChannel, and #SpiceAudio + * @stability: Stable + * @include: channel-record.h + * + * #SpiceRecordChannel class handles an audio recording stream. The + * audio stream should start when #SpiceRecordChannel::record-start is + * emitted and should be stopped when #SpiceRecordChannel::record-stop + * is received. + * + * The audio is sent to the guest by calling spice_record_send_data() + * with the recorded PCM data. + * + * Note: You may be interested to let the #SpiceAudio class play and + * record audio channels for your application. + */ + #define SPICE_RECORD_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_RECORD_CHANNEL, spice_record_channel)) @@ -95,6 +116,16 @@ static void spice_record_channel_class_init(SpiceRecordChannelClass *klass) channel_class->handle_msg = spice_record_handle_msg; channel_class->channel_up = channel_up; + /** + * SpiceRecordChannel::record-start: + * @channel: the #SpiceRecordChannel that emitted the signal + * @format: a #SPICE_AUDIO_FMT + * @channels: number of channels + * @rate: audio rate + * + * Notify when the recording should start, and provide audio format + * characteristics. + **/ signals[SPICE_RECORD_START] = g_signal_new("record-start", G_OBJECT_CLASS_TYPE(gobject_class), @@ -106,6 +137,12 @@ static void spice_record_channel_class_init(SpiceRecordChannelClass *klass) 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT); + /** + * SpiceRecordChannel::record-stop: + * @channel: the #SpiceRecordChannel that emitted the signal + * + * Notify when the recording should stop. + **/ signals[SPICE_RECORD_STOP] = g_signal_new("record-stop", G_OBJECT_CLASS_TYPE(gobject_class), diff --git a/gtk/channel-record.h b/gtk/channel-record.h index 5b85f1d..a8d3470 100644 --- a/gtk/channel-record.h +++ b/gtk/channel-record.h @@ -48,6 +48,7 @@ struct _SpiceRecordChannelClass { void (*record_data)(SpiceRecordChannel *channel, gpointer *data, gint size); void (*record_stop)(SpiceRecordChannel *channel); + /*< private >*/ /* * If adding fields to this struct, remove corresponding * amount of padding to avoid changing overall struct size diff --git a/gtk/spice-audio.c b/gtk/spice-audio.c index 9e88ac8..ef35499 100644 --- a/gtk/spice-audio.c +++ b/gtk/spice-audio.c @@ -19,6 +19,19 @@ * simple audio init dispatcher */ +/** + * SECTION:spice-audio + * @short_description: a helper to play and to record audio channels + * @title: Spice Audio + * @section_id: + * @see_also: #SpiceRecordChannel, and #SpicePlaybackChannel + * @stability: Stable + * @include: spice-audio.h + * + * A class that handles the playback and record channels for your + * application, and connect them to the default sound system. + */ + #include "spice-client.h" #include "spice-common.h" @@ -37,6 +50,17 @@ static void spice_audio_init(SpiceAudio *self G_GNUC_UNUSED) } +/** + * spice_audio_new: + * @session: the #SpiceSession to connect to + * @context: a #GMainContext to attach to (or %NULL for default). + * @name: a name for the audio channels (or %NULL for default). + * + * Once instantiated, #SpiceAudio will handle the playback and record + * channels to stream to your local audio system. + * + * Returns: a new #SpiceAudio instance. + **/ SpiceAudio *spice_audio_new(SpiceSession *session, GMainContext *context, const char *name) { diff --git a/gtk/spice-audio.h b/gtk/spice-audio.h index 93f656f..272bb81 100644 --- a/gtk/spice-audio.h +++ b/gtk/spice-audio.h @@ -50,6 +50,8 @@ struct _SpiceAudio { struct _SpiceAudioClass { GObjectClass parent_class; + + /*< private >*/ gchar _spice_reserved[SPICE_RESERVED_PADDING]; }; diff --git a/gtk/spice-channel.c b/gtk/spice-channel.c index 50d7346..8a48d6e 100644 --- a/gtk/spice-channel.c +++ b/gtk/spice-channel.c @@ -36,13 +36,27 @@ static void spice_channel_send_msg(SpiceChannel *channel, spice_msg_out *out, gb static void spice_channel_send_link(SpiceChannel *channel); static void channel_disconnect(SpiceChannel *channel); +/** + * SECTION:spice-channel + * @short_description: the base channel class + * @title: Spice Channel + * @section_id: + * @see_also: #SpiceSession, #SpiceMainChannel and other channels + * @stability: Stable + * @include: spice-channel.h + * + * #SpiceChannel is the base class for the different kind of Spice + * channel connections, such as #SpiceMainChannel, or + * #SpiceInputsChannel. + */ + /* ------------------------------------------------------------------ */ /* gobject glue */ #define SPICE_CHANNEL_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE ((obj), SPICE_TYPE_CHANNEL, spice_channel)) -G_DEFINE_TYPE (SpiceChannel, spice_channel, G_TYPE_OBJECT); +G_DEFINE_TYPE(SpiceChannel, spice_channel, G_TYPE_OBJECT); /* Properties */ enum { @@ -252,6 +266,14 @@ static void spice_channel_class_init(SpiceChannelClass *klass) G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * SpiceChannel::channel-event: + * @channel: the channel that emitted the signal + * @event: a #SpiceChannelEvent + * + * The #SpiceChannel::channel-event signal is emitted when the + * state of the connection change. + **/ signals[SPICE_CHANNEL_EVENT] = g_signal_new("channel-event", G_OBJECT_CLASS_TYPE(gobject_class), @@ -263,6 +285,15 @@ static void spice_channel_class_init(SpiceChannelClass *klass) 1, G_TYPE_INT); + /** + * SpiceChannel::open-fd: + * @channel: the channel that emitted the signal + * @with_tls: wether TLS connection is requested + * + * The #SpiceChannel::open-fd signal is emitted when a new + * connection is requested. This signal is emitted when the + * connection is made with spice_session_open_fd(). + **/ signals[SPICE_CHANNEL_OPEN_FD] = g_signal_new("open-fd", G_OBJECT_CLASS_TYPE(gobject_class), @@ -1007,7 +1038,7 @@ static void spice_channel_recv_msg(SpiceChannel *channel) * * Create a new #SpiceChannel of type @type, and channel ID @id. * - * Returns: + * Returns: a #SpiceChannel **/ SpiceChannel *spice_channel_new(SpiceSession *s, int type, int id) { @@ -1301,7 +1332,7 @@ static gboolean channel_connect(SpiceChannel *channel) * * Connect the channel, using #SpiceSession connection informations * - * Returns: #TRUE on success. + * Returns: %TRUE on success. **/ gboolean spice_channel_connect(SpiceChannel *channel) { @@ -1315,7 +1346,7 @@ gboolean spice_channel_connect(SpiceChannel *channel) * * Connect the channel using @fd socket. * - * Returns: #TRUE on success. + * Returns: %TRUE on success. **/ gboolean spice_channel_open_fd(SpiceChannel *channel, int fd) { @@ -1385,8 +1416,9 @@ static void channel_disconnect(SpiceChannel *channel) * @channel: * @reason: a channel event emitted on main context (or #SPICE_CHANNEL_NONE) * - * Close socket and reset connection specific data, then emit @reason - * on main context if not #SPICE_CHANNEL_NONE. + * Close the socket and reset connection specific data. Finally, emit + * @reason #SpiceChannel::channel-event on main context if not + * #SPICE_CHANNEL_NONE. **/ void spice_channel_disconnect(SpiceChannel *channel, SpiceChannelEvent reason) { @@ -1429,7 +1461,7 @@ static gboolean test_capability(GArray *caps, guint32 cap) * * Test availability of specific channel-kind capability of the remote. * - * Returns: #TRUE if @cap, a specific channel capability, is available. + * Returns: %TRUE if @cap, a specific channel capability, is available. **/ gboolean spice_channel_test_capability(SpiceChannel *self, guint32 cap) { diff --git a/gtk/spice-channel.h b/gtk/spice-channel.h index 6d42810..1198e83 100644 --- a/gtk/spice-channel.h +++ b/gtk/spice-channel.h @@ -34,6 +34,20 @@ G_BEGIN_DECLS typedef struct spice_msg_in spice_msg_in; typedef struct spice_msg_out spice_msg_out; +/** + * SpiceChannelEvent: + * + * @SPICE_CHANNEL_NONE: no event, or ignored event + * @SPICE_CHANNEL_OPENED: connection is authentified and ready + * @SPICE_CHANNEL_CLOSED: connection is closed normally + * @SPICE_CHANNEL_ERROR_CONNECT: connection error + * @SPICE_CHANNEL_ERROR_TLS: SSL error + * @SPICE_CHANNEL_ERROR_LINK: error during link process + * @SPICE_CHANNEL_ERROR_AUTH: authentication error + * @SPICE_CHANNEL_ERROR_IO: IO error + * + * An event, emitted by #SpiceChannel::channel-event signal. + **/ typedef enum { SPICE_CHANNEL_NONE = 0, @@ -57,16 +71,19 @@ struct _SpiceChannelClass { GObjectClass parent_class; + /*< private >*/ /* virtual methods, coroutine context */ void (*handle_msg)(SpiceChannel *channel, spice_msg_in *msg); void (*channel_up)(SpiceChannel *channel); void (*iterate_write)(SpiceChannel *channel); void (*iterate_read)(SpiceChannel *channel); + /*< public >*/ /* signals, system context */ void (*channel_event)(SpiceChannel *channel, SpiceChannelEvent event); void (*open_fd)(SpiceChannel *channel, int with_tls); + /*< private >*/ /* * If adding fields to this struct, remove corresponding * amount of padding to avoid changing overall struct size diff --git a/gtk/spice-grabsequence.h b/gtk/spice-grabsequence.h index d611186..fe58fc1 100644 --- a/gtk/spice-grabsequence.h +++ b/gtk/spice-grabsequence.h @@ -32,6 +32,7 @@ G_BEGIN_DECLS typedef struct _SpiceGrabSequence SpiceGrabSequence; struct _SpiceGrabSequence { + /*< private >*/ guint nkeysyms; guint *keysyms; diff --git a/gtk/spice-session.c b/gtk/spice-session.c index 3456a24..ecb7358 100644 --- a/gtk/spice-session.c +++ b/gtk/spice-session.c @@ -45,6 +45,37 @@ struct spice_session { gboolean client_provided_sockets; }; +/** + * SECTION:spice-session + * @short_description: handles connection details, and active channels + * @title: Spice Session + * @section_id: + * @see_also: #SpiceChannel, and the GTK widget #SpiceDisplay + * @stability: Stable + * @include: spice-session.h + * + * The #SpiceSession class handles all the #SpiceChannel connections. + * It's also the class that contains connections informations, such as + * #SpiceSession:host and #SpiceSession:port. + * + * You can simply set the property #SpiceSession:uri to something like + * "spice://127.0.0.1?port=5930" to configure your connection details. + * + * You may want to connect to #SpiceSession::channel-new signal, to be + * informed of the availability of channels and to interact with + * them. + * + * For example, when the #SpiceInputsChannel is available and get the + * event #SPICE_CHANNEL_OPENED, you can send key events with + * spice_inputs_key_press(). When the #SpiceMainChannel is available, + * you can start sharing the clipboard... . + * + * + * Once #SpiceSession properties set, you can call + * spice_session_connect() to start connecting and communicating with + * a Spice server. + */ + /* ------------------------------------------------------------------ */ /* gobject glue */ @@ -285,7 +316,7 @@ static void spice_session_class_init(SpiceSessionClass *klass) (gobject_class, PROP_HOST, g_param_spec_string("host", "Host", - "remote host", + "Remote host", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | @@ -297,7 +328,7 @@ static void spice_session_class_init(SpiceSessionClass *klass) (gobject_class, PROP_PORT, g_param_spec_string("port", "Port", - "remote port (plaintext)", + "Remote port (plaintext)", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | @@ -309,7 +340,7 @@ static void spice_session_class_init(SpiceSessionClass *klass) (gobject_class, PROP_TLS_PORT, g_param_spec_string("tls-port", "TLS port", - "remote port (encrypted)", + "Remote port (encrypted)", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | @@ -365,6 +396,13 @@ static void spice_session_class_init(SpiceSessionClass *klass) G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * SpiceSession::channel-new: + * @session: the session that emitted the signal + * @channel: the new #SpiceChannel + * + * The #SpiceSession::channel-new signal is emitted each time a #SpiceChannel is created. + **/ signals[SPICE_SESSION_CHANNEL_NEW] = g_signal_new("channel-new", G_OBJECT_CLASS_TYPE(gobject_class), @@ -376,6 +414,13 @@ static void spice_session_class_init(SpiceSessionClass *klass) 1, SPICE_TYPE_CHANNEL); + /** + * SpiceSession::channel-destroy: + * @session: the session that emitted the signal + * @channel: the destroyed #SpiceChannel + * + * The #SpiceSession::channel-destroy signal is emitted each time a #SpiceChannel is destroyed. + **/ signals[SPICE_SESSION_CHANNEL_DESTROY] = g_signal_new("channel-destroy", G_OBJECT_CLASS_TYPE(gobject_class), @@ -393,12 +438,28 @@ static void spice_session_class_init(SpiceSessionClass *klass) /* ------------------------------------------------------------------ */ /* public functions */ +/** + * spice_session_new: + * + * Creates a new Spice session. + * + * Returns: a new #SpiceSession + **/ SpiceSession *spice_session_new(void) { return SPICE_SESSION(g_object_new(SPICE_TYPE_SESSION, NULL)); } +/** + * spice_session_connect: + * @session: + * + * Open the session using the #SpiceSession:host and + * #SpiceSession:port. + * + * Returns: %FALSE if the connection failed. + **/ gboolean spice_session_connect(SpiceSession *session) { spice_session *s = SPICE_SESSION_GET_PRIVATE(session); @@ -412,6 +473,17 @@ gboolean spice_session_connect(SpiceSession *session) return spice_channel_connect(s->cmain); } +/** + * spice_session_open_fd: + * @session: + * @fd: a file descriptor + * + * Open the session using the provided @fd socket file + * descriptor. This is useful if you create the fd yourself, for + * example to setup a SSH tunnel. + * + * Returns: + **/ gboolean spice_session_open_fd(SpiceSession *session, int fd) { spice_session *s = SPICE_SESSION_GET_PRIVATE(session); @@ -426,6 +498,7 @@ gboolean spice_session_open_fd(SpiceSession *session, int fd) return spice_channel_open_fd(s->cmain, fd); } +G_GNUC_INTERNAL gboolean spice_session_get_client_provided_socket(SpiceSession *session) { spice_session *s = SPICE_SESSION_GET_PRIVATE(session); @@ -434,6 +507,12 @@ gboolean spice_session_get_client_provided_socket(SpiceSession *session) return s->client_provided_sockets; } +/** + * spice_session_disconnect: + * @session: + * + * Disconnect the @session, and destroy all channels. + **/ void spice_session_disconnect(SpiceSession *session) { spice_session *s = SPICE_SESSION_GET_PRIVATE(session); @@ -457,6 +536,14 @@ void spice_session_disconnect(SpiceSession *session) s->connection_id = 0; } +/** + * spice_session_get_channels: + * @session: + * + * Get the list of current channels associated with this @session. + * + * Returns: a #GList of unowned SpiceChannels. + **/ GList *spice_session_get_channels(SpiceSession *session) { spice_session *s = SPICE_SESSION_GET_PRIVATE(session); diff --git a/gtk/spice-session.h b/gtk/spice-session.h index 64c427c..364667e 100644 --- a/gtk/spice-session.h +++ b/gtk/spice-session.h @@ -42,10 +42,11 @@ struct _SpiceSessionClass { GObjectClass parent_class; - /* Signals */ + /* signals */ void (*channel_new)(SpiceSession *session, SpiceChannel *channel); void (*channel_destroy)(SpiceSession *session, SpiceChannel *channel); + /*< private >*/ /* * If adding fields to this struct, remove corresponding * amount of padding to avoid changing overall struct size diff --git a/gtk/spice-util.c b/gtk/spice-util.c index 36ebb43..e75cc2e 100644 --- a/gtk/spice-util.c +++ b/gtk/spice-util.c @@ -21,8 +21,25 @@ #include "spice-util.h" +/** + * SECTION:spice-util + * @short_description: version and debugging functions + * @title: Utilities + * @section_id: + * @stability: Stable + * @include: spice-util.h + * + * Various functions for debugging and informational purposes. + */ + static gboolean debugFlag = FALSE; +/** + * spice_util_set_debug: + * @enabled: %TRUE or %FALSE + * + * Enable or disable Spice-GTK debugging messages. + **/ void spice_util_set_debug(gboolean enabled) { debugFlag = enabled; @@ -33,6 +50,11 @@ gboolean spice_util_get_debug(void) return debugFlag || g_getenv("SPICE_DEBUG") != NULL; } +/** + * spice_util_get_version_string: + * + * Returns: Spice-GTK version as a const string. + **/ const gchar *spice_util_get_version_string(void) { return VERSION; diff --git a/gtk/spice-widget.c b/gtk/spice-widget.c index 55c8f94..85fe1ba 100644 --- a/gtk/spice-widget.c +++ b/gtk/spice-widget.c @@ -31,6 +31,17 @@ #include <spice/vd_agent.h> +/** + * SECTION:spice-widget + * @short_description: a GTK display widget + * @title: Spice Display + * @section_id: + * @stability: Stable + * @include: spice-widget.h + * + * Various functions for debugging and informational purposes. + */ + #define SPICE_DISPLAY_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE((obj), SPICE_TYPE_DISPLAY, spice_display)) diff --git a/gtk/spice-widget.h b/gtk/spice-widget.h index 83957a6..cf48f43 100644 --- a/gtk/spice-widget.h +++ b/gtk/spice-widget.h @@ -52,6 +52,7 @@ struct _SpiceDisplayClass { void (*mouse_grab)(SpiceChannel *channel, gint grabbed); void (*keyboard_grab)(SpiceChannel *channel, gint grabbed); + /*< private >*/ /* * If adding fields to this struct, remove corresponding * amount of padding to avoid changing overall struct size |