[Spice-commits] server/cursor-channel.h

[Frediano Ziglio]

 server/cursor-channel.h |   34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

New commits:
commit 8d25e03371393a80b91f99374c6098d417f74db2
Author: Frediano Ziglio <fziglio at redhat.com>
Date:   Fri May 13 10:10:17 2016 +0100

    Add some comments to cursor-channel.h header
    
    Explain usage of the class.
    
    Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
    Acked-by: Jonathon Jongsma <jjongsma at redhat.com>

diff --git a/server/cursor-channel.h b/server/cursor-channel.h
index 6c89bc3..6aeac16 100644
--- a/server/cursor-channel.h
+++ b/server/cursor-channel.h
@@ -23,20 +23,52 @@
 #include "red-worker.h"
 #include "red-parse-qxl.h"
 
+/**
+ * This type it's a RedChannel class which implement cursor (mouse)
+ * movements.
+ * A pointer to CursorChannel can be converted to a RedChannel.
+ */
 typedef struct CursorChannel CursorChannel;
 
+/**
+ * Create CursorChannel.
+ * Since CursorChannel is intended to be run in a separate thread,
+ * it does not register its own client callbacks since they would
+ * be called from a different thread. Therefore users of this
+ * class are responsible for registering their own client callbacks
+ * for CursorChannel. These 'wrapper' client callbacks must forward
+ * execution on to the CursorChannel thread.
+ * cursor_channel_client_migrate() and cursor_channel_connect() are
+ * provided as helper functions and should only be called from the
+ * CursorChannel thread.
+ */
 CursorChannel*       cursor_channel_new         (RedWorker *worker);
-void                 cursor_channel_disconnect  (CursorChannel *cursor_channel);
+
+/**
+ * Cause the channel to disconnect all clients
+ */
+void                 cursor_channel_disconnect  (CursorChannel *cursor);
 void                 cursor_channel_reset       (CursorChannel *cursor);
 void                 cursor_channel_init        (CursorChannel *cursor);
 void                 cursor_channel_process_cmd (CursorChannel *cursor, RedCursorCmd *cursor_cmd);
 void                 cursor_channel_set_mouse_mode(CursorChannel *cursor, uint32_t mode);
+
+/**
+ * Connect a new client to CursorChannel.
+ * This is the equivalent of RedChannel client connect callback.
+ * See comment on cursor_channel_new.
+ */
 void                 cursor_channel_connect     (CursorChannel *cursor, RedClient *client, 
                                                  RedsStream *stream,
                                                  int migrate,
                                                  uint32_t *common_caps, int num_common_caps,
                                                  uint32_t *caps, int num_caps);
 
+/**
+ * Migrate a client channel from a CursorChannel.
+ * This is the equivalent of RedChannel client migrate callback.
+ * See comment on cursor_channel_new.
+ */
 void                 cursor_channel_client_migrate(RedChannelClient *client);
 
 #endif /* CURSOR_CHANNEL_H_ */