ILocalRegistry.CreateInstance Method

Article
04/22/2008

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

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

Syntax

'Déclaration
Function CreateInstance ( _
    clsid As Guid, _
    punkOuter As Object, _
    ByRef riid As Guid, _
    dwFlags As UInteger, _
    <OutAttribute> ByRef ppvObj As IntPtr _
) As Integer
'Utilisation
Dim instance As ILocalRegistry
Dim clsid As Guid
Dim punkOuter As Object
Dim riid As Guid
Dim dwFlags As UInteger
Dim ppvObj As IntPtr
Dim returnValue As Integer

returnValue = instance.CreateInstance(clsid, _
    punkOuter, riid, dwFlags, ppvObj)

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
)

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

Parameters

clsid
Type: System.Guid

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

punkOuter
Type: System.Object

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

riid
Type: System.Guid%

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

dwFlags
Type: System.UInt32

[in] Flags controlling the instance creation from the CLSCTX enumeration. Specifies a value of CLSCTX_INPROC_SERVER.

ppvObj
Type: System.IntPtr%

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

Return Value

Type: System.Int32

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

Remarks

COM Signature

From objext.idl:

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

The CreateInstance method is equivalent to COM's CoCreateInstance function. It creates a single uninitialized object of the kind 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 associated with the specified CLSID, creates an uninitialized instance of the object, and releases the class object. This method encapsulates calls to the COM function CoGetClassObject to get a pointer to the object's class factory, to CreateInstance to create an instance of the object, and to Release the reference to the object's class factory.

Note

Call CreateInstance when you want to create a single instance of an object based on a CLSID and do not need 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 (for example, [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\8.0\CLSID]). In this section of the registry, InProcServer32 is used as a value rather than a subkey. We only support instantiating objects 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 using COM's CoCreateInstance function.

Permissions

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Partager via