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