changeset 18836:5464e5d8603b

merge of '2dd575a1471bdca9f2d49e17e92165d3b6ddcca0' and '5e5168d639fb9a3a29ab3fe44b976d6d25924403'

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/ui-ops.dox	Wed Aug 08 00:29:26 2007 +0000
@@ -0,0 +1,24 @@
+/** @page ui-ops UiOps structures
+
+  When implementing a UI for libpurple, you need to fill in various UiOps
+  structures:
+
+   - #PurpleAccountUiOps
+   - #PurpleBlistUiOps
+   - #PurpleConnectionUiOps
+   - #PurpleConversationUiOps
+   - #PurpleCoreUiOps
+   - #PurpleDebugUiOps
+   - #PurpleDnsQueryUiOps
+   - #PurpleEventLoopUiOps
+   - #PurpleIdleUiOps
+   - #PurpleNotifyUiOps
+   - #PurplePrivacyUiOps
+   - #PurpleRequestUiOps
+   - #PurpleRoomlistUiOps
+   - #PurpleSoundUiOps
+   - #PurpleWhiteboardUiOps
+   - #PurpleXferUiOps
+
+ */
+// vim: ft=c.doxygen

--- a/libpurple/connection.h	Wed Aug 08 00:29:20 2007 +0000
+++ b/libpurple/connection.h	Wed Aug 08 00:29:26 2007 +0000
@@ -60,15 +60,52 @@
 #include "plugin.h"
 #include "status.h"
 
+/** Connection UI operations.  Used to notify the user of changes to
+ *  connections, such as being disconnected, and to respond to the
+ *  underlying network connection appearing and disappearing.  UIs should
+ *  call #purple_connections_set_ui_ops() with an instance of this struct.
+ *
+ *  @see @ref ui-ops
+ */
 typedef struct
 {
-	void (*connect_progress)(PurpleConnection *gc, const char *text,
-							 size_t step, size_t step_count);
+	/** When an account is connecting, this operation is called to notify
+	 *  the UI of what is happening, as well as which @a step out of @a
+	 *  step_count has been reached (which might be displayed as a progress
+	 *  bar).
+	 */
+	void (*connect_progress)(PurpleConnection *gc,
+	                         const char *text,
+	                         size_t step,
+	                         size_t step_count);
+	/** Called when a connection is established (just before the
+	 *  @ref signed-on signal).
+	 */
 	void (*connected)(PurpleConnection *gc);
+	/** Called when a connection is ended (between the @ref signing-off
+	 *  and @ref signed-off signals).
+	 */
 	void (*disconnected)(PurpleConnection *gc);
+	/** Used to display connection-specific notices.  (Pidgin's Gtk user
+	 *  interface implements this as a no-op; #purple_connection_notice(),
+	 *  which uses this operation, is not used by any of the protocols
+	 *  shipped with libpurple.)
+	 */
 	void (*notice)(PurpleConnection *gc, const char *text);
+	/** Called when an error causes a connection to be disconnected.
+	 *  Called before #disconnected.
+	 *  @param text  a localized error message.
+	 */
 	void (*report_disconnect)(PurpleConnection *gc, const char *text);
+	/** Called when libpurple discovers that the computer's network
+	 *  connection is active.  On Linux, this uses Network Manager if
+	 *  available; on Windows, it uses Win32's network change notification
+	 *  infrastructure.
+	 */
 	void (*network_connected)();
+	/** Called when libpurple discovers that the computer's network
+	 *  connection has gone away.
+	 */
 	void (*network_disconnected)();
 
 	void (*_purple_reserved1)(void);