Changeset 6851 in vbox for trunk/include/VBox/com

Timestamp:

Feb 7, 2008 4:02:11 PM (17 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

27977

Message:

Ported r27277:27975 (array support) from branches/dmik/s2.

Location:

trunk/include/VBox/com

Files:

• array.h (added)
• defs.h (modified) (3 diffs)
• string.h (modified) (5 diffs)

trunk/include/VBox/com/defs.h

@@ -70 +70 @@
 
 /**
+ * Declares an input safearray parameter in the COM method implementation. Also 
+ * used to declare the COM attribute setter parameter. Corresponds to either of 
+ * the following XIDL definitions: 
+ * <pre>
+ *  <param name="arg" ... dir="in" safearray="yes"/>
+ *  ...
+ *  <attribute name="arg" ... safearray="yes"/>
+ * </pre> 
+ * 
+ * The method implementation should use the com::SafeArray helper class to work 
+ * with parameters declared using this define. 
+ *  
+ * @param aType Array element type.
+ * @param aArg  Parameter/attribute name.
+ */
+#define ComSafeArrayIn(aType, aArg)     SAFEARRAY **aArg
+
+/** 
+ * Expands to @true if the given input safearray parameter is a "null pointer" 
+ * which makes it impossible to use it for reading safearray data. 
+ */ 
+#define ComSafeArrayInIsNull(aArg)      (aArg == NULL)
+
+/** 
+ * Wraps the given parameter name to generate an expression that is suitable for
+ * passing the parameter to functions that take input safearray parameters 
+ * declared using the ComSafeArrayIn marco. 
+ *  
+ * @param aArg  Parameter name to wrap. The given parameter must be declared 
+ *              within the calling function using the ComSafeArrayIn macro.
+ */
+#define ComSafeArrayInArg(aArg)         aArg
+
+/**
+ * Declares an output safearray parameter in the COM method implementation. Also 
+ * used to declare the COM attribute getter parameter. Corresponds to either of 
+ * the following XIDL definitions:
+ * <pre>
+ *  <param name="arg" ... dir="out" safearray="yes"/>
+ *  <param name="arg" ... dir="return" safearray="yes"/>
+ *  ...
+ *  <attribute name="arg" ... safearray="yes"/>
+ * </pre> 
+ *  
+ * The method implementation should use the com::SafeArray helper class to work 
+ * with parameters declared using this define. 
+ *  
+ * @param aType Array element type.
+ * @param aArg  Parameter/attribute name.
+ */
+#define ComSafeArrayOut(aType, aArg)    SAFEARRAY **aArg
+
+/** 
+ * Expands to @true if the given output safearray parameter is a "null pointer" 
+ * which makes it impossible to use it for returning a safearray.
+ */ 
+#define ComSafeArrayOutIsNull(aArg)     (aArg == NULL)
+
+/** 
+ * Wraps the given parameter name to generate an expression that is suitable for
+ * passing the parameter to functions that take output safearray parameters 
+ * declared using the ComSafeArrayOut marco. 
+ *  
+ * @param aArg  Parameter name to wrap. The given parameter must be declared 
+ *              within the calling function using the ComSafeArrayOut macro.
+ */
+#define ComSafeArrayOutArg(aArg)        aArg
+
+/**
  *  Returns the const reference to the IID (i.e., |const GUID &|) of the given
  *  interface.
@@ -79 +148 @@
 #else /* defined (RT_OS_WINDOWS) */
 
-#error "VBOX_WITH_XPCOM is not defined!"
+#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
 
 #endif /* defined (RT_OS_WINDOWS) */
@@ -156 +225 @@
 /* a type for an output GUID parameter in the interface method declaration */
 #define GUIDPARAMOUT        nsID **
+
+/* safearray input parameter macros */
+#define ComSafeArrayIn(aType, aArg)         PRUint32 aArg##Size, aType *aArg
+#define ComSafeArrayInIsNull(aArg)          (aArg == NULL)
+#define ComSafeArrayInArg(aArg)             aArg##Size, aArg
+
+/* safearray output parameter macros */
+#define ComSafeArrayOut(aType, aArg)        PRUint32 *aArg##Size, aType **aArg
+#define ComSafeArrayOutIsNull(aArg)         (aArg == NULL)
+#define ComSafeArrayOutArg(aArg)            aArg##Size, aArg
 
 /* CLSID and IID for compatibility with Win32 */

trunk/include/VBox/com/string.h

@@ -184 +184 @@
 
     /**
-     *  Intended to assign instances to |BSTR| out parameters from within the
-     *  interface method. Transfers the ownership of the duplicated string to
-     *  the caller.
+     *  Intended to assign copies of instances to |BSTR| out parameters from
+     *  within the interface method. Transfers the ownership of the duplicated
+     *  string to the caller.
      */
     const Bstr &cloneTo (BSTR *pstr) const
@@ -199 +199 @@
 
     /**
-     *  Intended to assign instances to |char *| out parameters from within the
-     *  interface method. Transfers the ownership of the duplicated string to
-     *  the caller.
+     *  Intended to assign instances to |BSTR| out parameters from within the
+     *  interface method. Transfers the ownership of the original string to the
+     *  caller and resets the instance to null.
+     *
+     *  As opposed to cloneTo(), this method doesn't create a copy of the
+     *  string.
+     */
+    Bstr &detachTo (BSTR *pstr)
+    {
+        *pstr = bstr;
+        bstr = NULL;
+        return *this;
+    }
+
+    /**
+     *  Intended to assign copies of instances to |char *| out parameters from
+     *  within the interface method. Transfers the ownership of the duplicated
+     *  string to the caller.
      */
     const Bstr &cloneTo (char **pstr) const;
@@ -211 +226 @@
     BSTR *asOutParam() { setNull(); return &bstr; }
 
-    /** 
+    /**
      *  Static immutable null object. May be used for comparison purposes.
      */
@@ -405 +420 @@
 
     /**
+     *  Intended to assign instances to |char *| out parameters from within the
+     *  interface method. Transfers the ownership of the original string to the
+     *  caller and resets the instance to null.
+     *
+     *  As opposed to cloneTo(), this method doesn't create a copy of the
+     *  string.
+     */
+    Utf8Str &detachTo (char **pstr)
+    {
+        *pstr = str;
+        str = NULL;
+        return *this;
+    }
+
+    /**
      *  Intended to assign instances to |BSTR| out parameters from within the
      *  interface method. Transfers the ownership of the duplicated string to the
@@ -425 +455 @@
     char **asOutParam() { setNull(); return &str; }
 
-    /** 
+    /**
      *  Static immutable null object. May be used for comparison purposes.
      */