ILocalRegistry3.CreateInstance Method

  • Article

Creates an instance of a class that is listed in the local registry.

Namespace:  Microsoft.VisualStudio.Shell.Interop
Assembly:  Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Declaration
Function CreateInstance ( _
    clsid As Guid, _
    punkOuter As Object, _
    ByRef riid As Guid, _
    dwFlags As UInteger, _
    <OutAttribute> ByRef ppvObj As IntPtr _
) As Integer

int CreateInstance(
    Guid clsid,
    Object punkOuter,
    ref Guid riid,
    uint dwFlags,
    out IntPtr ppvObj
)

int CreateInstance(
    [InAttribute] Guid clsid, 
    [InAttribute] Object^ punkOuter, 
    [InAttribute] Guid% riid, 
    [InAttribute] unsigned int dwFlags, 
    [OutAttribute] IntPtr% ppvObj
)

abstract CreateInstance : 
        clsid:Guid * 
        punkOuter:Object * 
        riid:Guid byref * 
        dwFlags:uint32 * 
        ppvObj:IntPtr byref -> int

function CreateInstance(
    clsid : Guid, 
    punkOuter : Object, 
    riid : Guid, 
    dwFlags : uint, 
    ppvObj : IntPtr
) : int

Parameters

  • clsid
    Type: Guid

    [in] Class identifier (CLSID) of the requested object. This CLSID is associated with the data and code that is used to create the object.

  • punkOuter
    Type: Object

    [in] Pointer to the controlling instance of IUnknown of the aggregate that uses the newly created object. A value of nulla null reference (Nothing in Visual Basic) indicates that the object is not created as part of an aggregate. If non-null, this is a pointer to the IUnknown interface of the aggregate object (the controlling IUnknown).

  • riid
    Type: Guid%

    [in] Interface to be used to communicate with the object. For example, IID_IClassFactory.

  • dwFlags
    Type: UInt32

    [in] Flags that control the instance creation from the CLSCTX enumeration. Specify a value of CLSCTX_INPROC_SERVER.

  • ppvObj
    Type: IntPtr%

    [out] Address of the pointer variable that receives the interface pointer that is requested in riid. On successful return, ppvObj contains the requested interface pointer. On failure, ppvObj contains nulla null reference (Nothing in Visual Basic).

Return Value

Type: Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From objext.idl:

HRESULT ILocalRegistry3::CreateInstance(
    [in] CLSID clsid, 
    [in] IUnknown* punkOuter, 
    [in] REFIID riid, 
    [in] DWORD dwFlags, 
    [out] void** ppvObj
);

The CreateInstance method is equivalent to CoCreateInstance. It creates a single uninitialized object of the kind that is associated with the specified CLSID and returns any requested interface pointers.

CreateInstance looks up the class object in the local registry of registered objects, connects to the class object that is associated with the specified CLSID, creates an uninitialized instance of the object, and releases the class object. This method encapsulates calls to the OLE function CoGetClassObject to get a pointer to the class factory of the object, and to CreateInstance to create an instance of the object and release the reference to the class factory.

Note

Call CreateInstance when you want to create a single instance of an object that is based on a CLSID and do not have to keep the class factory object to create other instances of the object. To create multiple objects from a single class object, use the GetClassObjectOfClsid method.

This method registers an object in the local registry hive [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\7.0\CLSID]. In this section of the registry, InProcServer32 is used as a value rather than a subkey. Instantiating objects is only supported on the main UI thread.

Specify a value of CLSCTX_INPROC_SERVER for the dwFlags parameter to instantiate the object locally. If you do not specify this value, then the object will be instantiated globally by using CoCreateInstance.

.NET Framework Security

See Also

Reference

ILocalRegistry3 Interface

Microsoft.VisualStudio.Shell.Interop Namespace