Correctly initialise ref count in custom scheme class factory.

[wxWidgets.git] / interface / wx / msw / ole / automtn.h

diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h
index 22f47a1d8d121ba2bc5bd31783335584c90366a7..916bc1b80dce8ae267bbec0bcfeedb6df7808800 100644 (file)
--- a/interface/wx/msw/ole/automtn.h
+++ b/interface/wx/msw/ole/automtn.h
@@ -3,9 +3,46 @@
 // Purpose:     interface of wxAutomationObject
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Automation object creation flags.
+
+    These flags can be used with wxAutomationObject::GetInstance().
+
+    @since 2.9.2
+*/
+enum wxAutomationInstanceFlags
+{
+    /**
+        Only use the existing instance, never create a new one.
+
+        This flag can be used to forbid the creation of a new instance if none
+        is currently running.
+     */
+    wxAutomationInstance_UseExistingOnly = 0,
+
+    /**
+        Create a new instance if there are no existing ones.
+
+        This flag corresponds to the default behaviour of
+        wxAutomationObject::GetInstance() and means that if getting an existing
+        instance failed, we should call wxAutomationObject::CreateInstance() to
+        create a new one.
+     */
+    wxAutomationInstance_CreateIfNeeded = 1,
+
+    /**
+        Do not show an error message if no existing instance is currently
+        running.
+
+        All other errors will still be reported as usual.
+     */
+    wxAutomationInstance_SilentIfNone = 2
+};
+
+
 /**
     @class wxAutomationObject
 
@@ -75,11 +112,11 @@ public:
     //@}
 
     /**
-        Creates a new object based on the class id, returning @true if the object was
+        Creates a new object based on the ProgID, returning @true if the object was
         successfully created,
         or @false if not.
     */
-    bool CreateInstance(const wxString& classId) const;
+    bool CreateInstance(const wxString& progId) const;
 
     /**
         Checks if the object is in a valid state.
@@ -93,20 +130,37 @@ public:
 
     /**
         Gets the IDispatch pointer.
+
+        Notice that the return value of this function is an untyped pointer but
+        it can be safely cast to @c IDispatch.
     */
-    IDispatch* GetDispatchPtr() const;
+    void* GetDispatchPtr() const;
 
     /**
-        Retrieves the current object associated with a class id, and attaches the
-        IDispatch pointer
-        to this object. Returns @true if a pointer was successfully retrieved, @false
+        Retrieves the current object associated with the specified ProgID, and
+        attaches the IDispatch pointer to this object.
+
+        If attaching to an existing object failed and @a flags includes
+        wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
+        Otherwise this function will normally log an error message which may be
+        undesirable if the object may or may not exist. The
+        wxAutomationInstance_SilentIfNone flag can be used to prevent the error
+        from being logged in this case.
+
+        Returns @true if a pointer was successfully retrieved, @false
         otherwise.
+
         Note that this cannot cope with two instances of a given OLE object being
         active simultaneously,
         such as two copies of Excel running. Which object is referenced cannot
         currently be specified.
+
+        @param progId COM ProgID, e.g. "Excel.Application"
+        @param flags The creation flags (this parameters was added in wxWidgets
+            2.9.2)
     */
-    bool GetInstance(const wxString& classId) const;
+    bool GetInstance(const wxString& progId,
+                     int flags = wxAutomationInstance_CreateIfNeeded) const;
 
     /**
         Retrieves a property from this object, assumed to be a dispatch pointer, and