Warn about conn, dom and net fields in virterror

        * include/libvirt/virterror.h: Warn about the use of
          conn, dom and net fields in virterror.

diff --git a/ChangeLog b/ChangeLog
index 7f9f7fc2491d1c9c06b45a4e719f09f9c79ea821..453dc1378a68fa8d8371b9ce268131a8c6ea6292 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Wed Apr  9 14:56:00 BST 2008 Richard W.M. Jones <rjones@redhat.com>
+
+       Warn about conn, dom and net fields in virterror
+       * include/libvirt/virterror.h: Warn about the use of
+         conn, dom and net fields in virterror.
+
 Wed Apr  9 14:46:00 BST 2008 Richard W.M. Jones <rjones@redhat.com>
 
        Remove extraneous underscore

diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h
index a4155b346a039ec2eb6416e69d22fb7b9688b817..460b42f383cb10374d7f2547c8e5c26c0bfa1880 100644 (file)
--- a/include/libvirt/virterror.h
+++ b/include/libvirt/virterror.h
@@ -63,6 +63,10 @@ typedef enum {
  * virError:
  *
  * A libvirt Error instance.
+ *
+ * The conn, dom and net fields should be used with extreme care.
+ * Reference counts are not incremented so the underlying objects
+ * may be deleted without notice after the error has been delivered.
  */
 
 typedef struct _virError virError;
@@ -72,14 +76,14 @@ struct _virError {
     int                domain; /* What part of the library raised this error */
     char       *message;/* human-readable informative error message */
     virErrorLevel level;/* how consequent is the error */
-    virConnectPtr conn;        /* the connection if available */
-    virDomainPtr dom;  /* the domain if available */
+    virConnectPtr conn;        /* connection if available, see note above */
+    virDomainPtr dom;  /* domain if available, see note above */
     char       *str1;  /* extra string information */
     char       *str2;  /* extra string information */
     char       *str3;  /* extra string information */
     int                int1;   /* extra number information */
     int                int2;   /* extra number information */
-    virNetworkPtr net; /* the network if available */
+    virNetworkPtr net; /* network if available, see note above */
 };
 
 /**