ptr::CreateInstance

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at ptr::CreateInstance.

Creates an instance of a COM object within a com::ptr.

Syntax

void CreateInstance(  
   System::String ^ progid,  
   LPUNKNOWN pouter,  
   DWORD cls_context  
);  
void CreateInstance(  
   System::String ^ progid,  
   LPUNKNOWN pouter  
);  
void CreateInstance(  
   System::String ^ progid  
);  
void CreateInstance(  
   const wchar_t * progid,  
   LPUNKNOWN pouter,  
   DWORD cls_context  
);  
void CreateInstance(  
   const wchar_t * progid,  
   LPUNKNOWN pouter  
);  
void CreateInstance(  
   const wchar_t * progid  
);  
void CreateInstance(  
   REFCLSID rclsid,  
   LPUNKNOWN pouter,  
   DWORD cls_context  
);  
void CreateInstance(  
   REFCLSID rclsid,  
   LPUNKNOWN pouter  
);  
void CreateInstance(  
   REFCLSID rclsid  
);

Parameters

progid
A ProgID string.

pouter
Pointer to the aggregate object's IUnknown interface (the controlling IUnknown). If pouter is not specified, NULL is used.

cls_context
Context in which the code that manages the newly created object will run. The values are taken from the CLSCTX enumeration. If cls_context is not specified, the value CLSCTX_ALL is used.

rclsid
CLSID associated with the data and code that will be used to create the object.

Exceptions

If the com::ptr already owns a reference to a COM object, CreateInstance throws InvalidOperationException.

This function calls CoCreateInstance and uses ThrowExceptionForHR to convert any error HRESULT to an appropriate exception.

Remarks

CreateInstance uses CoCreateInstance to create a new instance of the specified object, identified either from a ProgID or a CLSID. The com::ptr references the newly created object and will automatically release all owned references upon destruction.

Example

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. The class constructors use two different forms of CreateInstance to create the document object either from a ProgID or from a CLSID plus a CLSCTX.

// comptr_createinstance.cpp  
// compile with: /clr /link msxml2.lib  
#include <msxml2.h>  
#include <msclr\com\ptr.h>  
  
#import <msxml3.dll> raw_interfaces_only  
  
using namespace System;  
using namespace System::Runtime::InteropServices;  
using namespace msclr;  
  
// a ref class that uses a com::ptr to contain an   
// IXMLDOMDocument object  
ref class XmlDocument {  
public:  
   // construct the internal com::ptr with a null interface  
   // and use CreateInstance to fill it  
   XmlDocument(String^ progid) {  
      m_ptrDoc.CreateInstance(progid);     
   }  
   XmlDocument(REFCLSID clsid, DWORD clsctx) {  
      m_ptrDoc.CreateInstance(clsid, NULL, clsctx);  
   }  
  
   // note that the destructor will call the com::ptr destructor  
   // and automatically release the reference to the COM object  
  
private:  
   com::ptr<IXMLDOMDocument> m_ptrDoc;  
};  
  
// use the ref class to handle an XML DOM Document object  
int main() {  
   try {  
      // create the class from a progid string  
      XmlDocument doc1("Msxml2.DOMDocument.3.0");  
  
      // or from a clsid with specific CLSCTX  
      XmlDocument doc2(CLSID_DOMDocument30, CLSCTX_INPROC_SERVER);  
   }  
   catch (Exception^ e) {  
      Console::WriteLine(e);     
   }  
}

Requirements

Header file <msclr\com\ptr.h>

Namespace msclr::com

Share via