# OLEGuids Package
{: .no_toc }

**Author:** Krool. **Version:** 1.0.10.0. **On GitHub:** [Kr00l/VBCCR](https://github.com/Kr00l/VBCCR/tree/master/twinBASIC%20Package/OLEGuids), in the folder *twinBASIC Package/OLEGuids*.

A twinBASIC package that declares 25 OLE and COM interfaces and 11 structures in twinBASIC source, so that a 32-bit or 64-bit project can call or implement them without a type library.

The package is a twinBASIC implementation of `OLEGuids.tlb`, the type library of OLE interface and type definitions that Krool's VBCCR and VBFLXGRD controls (`VBCCRxx.OCX` and `VBFLXGRDxx.OCX`) use. It replaces `OLEGuids.tlb` in projects that build 64-bit programs, and works in 32-bit projects as well. This section documents version 1.0.10.0, published under the MIT licence.

## Using the package

Add the package in Project → References... (Ctrl-T) → the **Available Packages** tab. The interfaces and structures are then visible to the whole project. Two things can be done with an interface:

- **Call it.** Declare a variable of the interface type and assign an object to it. The assignment asks the object for that interface, and a call through the variable runs the object's method.
- **Implement it.** Name it in an [**Implements**](/tB/Core/Implements.md) statement in a class, and write each method. A class cannot implement an interface that has a `[PreserveSig]` member (see [How the declarations differ from Windows](#how-the-declarations-differ-from-windows)).

A name can be written bare (`IOleWindow`, `OLERECT`) or qualified with the package name (`OLEGuids.IOleWindow`, `OLEGuids.OLERECT`). The eleven structures are declared in a module named `OLEGuids`, which is why the qualified form works for them; the module has no page of its own.

```tb check_build
Private Function InPlaceWindow(ByVal Obj As Object) As LongPtr
    Dim w As IOleWindow = Obj
    Return w.GetWindow()
End Function
```

> [!NOTE] 1.0.10.0
> The package has no declaration named **IDispatch**. In a project that references **stdole**, as every default project does, the name is **stdole**'s declaration. A call through it is late-bound by name, and its four methods are not reached (see [IDispatch](/Reference/COM-Interfaces/IDispatch.md#the-stdole-declaration)). The package's [IDispatchUnrestricted](/tB/Packages/Contributed/OLEGuids/IDispatchUnrestricted.md) declares the four methods, and an object is assigned to a variable of that type like any other interface.

```tb check_build
Private Function HasTypeInfo(ByVal Obj As Object) As Boolean
    Dim d As IDispatchUnrestricted = Obj
    Dim count As Long
    d.GetTypeInfoCount count
    Return count > 0
End Function
```

## How the declarations differ from Windows

The interfaces that exist in Windows have their original interface identifiers, so an object written in another language can be called through them. The declarations differ from the C headers in these ways:

- **The HRESULT is hidden.** A **Sub**, and a **Function** that is not marked `[PreserveSig]`, returns nothing of the Windows method's HRESULT. A failure code raises a run-time error, and a success code other than `S_OK` is read with [**Err.LastHresult**](/tB/Modules/ErrObject/LastHresult.md). Where the Windows method has an output parameter for its result, the **Function**'s result takes its place.
- **`[PreserveSig]` members return the raw HRESULT** as a **Long**. A twinBASIC class cannot implement a member marked [**[PreserveSig]**](/tB/Core/Attributes.md#preservesig): the compiler reports TB5004, *unable to match this implementation to its interface member*. The interfaces with such a member are for calling, not for implementing: [IUnknownUnrestricted](/tB/Packages/Contributed/OLEGuids/IUnknownUnrestricted.md), [IOleObject](/tB/Packages/Contributed/OLEGuids/IOleObject.md), [IOleInPlaceObjectWindowless](/tB/Packages/Contributed/OLEGuids/IOleInPlaceObjectWindowless.md), [IOleControl](/tB/Packages/Contributed/OLEGuids/IOleControl.md), [IOleControlSite](/tB/Packages/Contributed/OLEGuids/IOleControlSite.md), [IOleInPlaceActiveObject](/tB/Packages/Contributed/OLEGuids/IOleInPlaceActiveObject.md), [IOleInPlaceSite](/tB/Packages/Contributed/OLEGuids/IOleInPlaceSite.md), [IPerPropertyBrowsing](/tB/Packages/Contributed/OLEGuids/IPerPropertyBrowsing.md) and [IRichEditOle](/tB/Packages/Contributed/OLEGuids/IRichEditOle.md). A class sets [**Err.ReturnHResult**](/tB/Modules/ErrObject/ReturnHResult.md) to return a specific HRESULT from a **Sub** it implements.
- **Pointers are `LongPtr`.** A parameter that is a pointer to a structure or to an interface the package does not declare (a `RECT*`, a `MSG*`, an `IMoniker*`) is a **LongPtr**. Pass the address of a variable with [**VarPtr**](/tB/Modules/Information/VarPtr.md), or `StrPtr` for a string.
- **Some declarations are partial.** [IOleObject](/tB/Packages/Contributed/OLEGuids/IOleObject.md) declares the first nine of the 21 methods of the Windows interface. The four stub interfaces --- [IOleClientSite](/tB/Packages/Contributed/OLEGuids/IOleClientSite.md), [IOleInPlaceFrame](/tB/Packages/Contributed/OLEGuids/IOleInPlaceFrame.md), [IStorage](/tB/Packages/Contributed/OLEGuids/IStorage.md) and [IDataObject](/tB/Packages/Contributed/OLEGuids/IDataObject.md) --- declare no methods; their description says to use the tbShellLib package for the full version. A stub is useful for naming the type of a parameter or a variable, not for calling.
- **Seven declarations are variants of a Windows interface.** [IUnknownUnrestricted](/tB/Packages/Contributed/OLEGuids/IUnknownUnrestricted.md) has no base interface, which makes the three methods of **IUnknown** callable. [IDispatchUnrestricted](/tB/Packages/Contributed/OLEGuids/IDispatchUnrestricted.md) declares the four methods of **IDispatch**, which the **stdole** declaration does not reach. [IEnumVARIANTUnrestricted](/tB/Packages/Contributed/OLEGuids/IEnumVARIANTUnrestricted.md) declares the **IEnumVARIANT** enumerator with **Long** counts. [IOleInPlaceActiveObjectVB](/tB/Packages/Contributed/OLEGuids/IOleInPlaceActiveObjectVB.md), [IOleControlVB](/tB/Packages/Contributed/OLEGuids/IOleControlVB.md), [IPerPropertyBrowsingVB](/tB/Packages/Contributed/OLEGuids/IPerPropertyBrowsingVB.md) and [IOleInPlaceObjectWindowlessVB](/tB/Packages/Contributed/OLEGuids/IOleInPlaceObjectWindowlessVB.md) are not Windows interfaces: they have Visual Basic-style signatures that a class can implement.

Every interface except the four `VB` variants is declared `[OleAutomation(False)]`, so it is not marked as an Automation interface. The contract of each method is that of the Windows interface, which Microsoft Learn documents; each interface page links to it.

## Interfaces

- [IDataObject](/tB/Packages/Contributed/OLEGuids/IDataObject.md) -- stub for the interface that transfers data between applications
- [IDispatchUnrestricted](/tB/Packages/Contributed/OLEGuids/IDispatchUnrestricted.md) -- finds and calls members of an automation object by name or dispatch identifier
- [IEnumVARIANTUnrestricted](/tB/Packages/Contributed/OLEGuids/IEnumVARIANTUnrestricted.md) -- enumerator of **Variant** values with **Long** counts
- [IObjectSafety](/tB/Packages/Contributed/OLEGuids/IObjectSafety.md) -- reports and sets an object's safety options for untrusted callers and data
- [IOleClientSite](/tB/Packages/Contributed/OLEGuids/IOleClientSite.md) -- stub for the container-side site of an embedded object
- [IOleControl](/tB/Packages/Contributed/OLEGuids/IOleControl.md) -- keyboard mnemonics, ambient property changes and event freezing of a control
- [IOleControlSite](/tB/Packages/Contributed/OLEGuids/IOleControlSite.md) -- the container-side site of a control
- [IOleControlVB](/tB/Packages/Contributed/OLEGuids/IOleControlVB.md) -- Visual Basic-style **GetControlInfo** and **OnMnemonic**
- [IOleInPlaceActiveObject](/tB/Packages/Contributed/OLEGuids/IOleInPlaceActiveObject.md) -- messages, activation and border changes for an in-place active object
- [IOleInPlaceActiveObjectVB](/tB/Packages/Contributed/OLEGuids/IOleInPlaceActiveObjectVB.md) -- Visual Basic-style **TranslateAccelerator**
- [IOleInPlaceFrame](/tB/Packages/Contributed/OLEGuids/IOleInPlaceFrame.md) -- stub for the container's frame window in in-place activation
- [IOleInPlaceObject](/tB/Packages/Contributed/OLEGuids/IOleInPlaceObject.md) -- activates and deactivates an object in place
- [IOleInPlaceObjectWindowless](/tB/Packages/Contributed/OLEGuids/IOleInPlaceObjectWindowless.md) -- window messages and drop target of an object that is active in place and has no window
- [IOleInPlaceObjectWindowlessVB](/tB/Packages/Contributed/OLEGuids/IOleInPlaceObjectWindowlessVB.md) -- Visual Basic-style **OnWindowMessage**
- [IOleInPlaceSite](/tB/Packages/Contributed/OLEGuids/IOleInPlaceSite.md) -- the container-side site for in-place activation
- [IOleInPlaceUIWindow](/tB/Packages/Contributed/OLEGuids/IOleInPlaceUIWindow.md) -- border space in a frame or document window
- [IOleObject](/tB/Packages/Contributed/OLEGuids/IOleObject.md) -- connects an embedded object to its site and performs its verbs
- [IOleWindow](/tB/Packages/Contributed/OLEGuids/IOleWindow.md) -- returns the window handle of an OLE object
- [IPerPropertyBrowsing](/tB/Packages/Contributed/OLEGuids/IPerPropertyBrowsing.md) -- display strings, property pages and predefined values of an object's properties
- [IPerPropertyBrowsingVB](/tB/Packages/Contributed/OLEGuids/IPerPropertyBrowsingVB.md) -- Visual Basic-style versions of three **IPerPropertyBrowsing** methods
- [IRichEditOle](/tB/Packages/Contributed/OLEGuids/IRichEditOle.md) -- the OLE objects in a Rich Edit control
- [IRichEditOleCallback](/tB/Packages/Contributed/OLEGuids/IRichEditOleCallback.md) -- what a Rich Edit control asks its container
- [ISpecifyPropertyPages](/tB/Packages/Contributed/OLEGuids/ISpecifyPropertyPages.md) -- lists the property pages of an object
- [IStorage](/tB/Packages/Contributed/OLEGuids/IStorage.md) -- stub for the structured-storage interface
- [IUnknownUnrestricted](/tB/Packages/Contributed/OLEGuids/IUnknownUnrestricted.md) -- the three methods of **IUnknown**, callable

## Types

- [OLEACCELMSG](/tB/Packages/Contributed/OLEGuids/OLEACCELMSG.md) -- a window message, with the layout of the Windows **MSG** structure
- [OLECADWORD](/tB/Packages/Contributed/OLEGuids/OLECADWORD.md) -- a counted array of **DWORD** values
- [OLECALPOLESTR](/tB/Packages/Contributed/OLEGuids/OLECALPOLESTR.md) -- a counted array of Unicode string pointers
- [OLECAUUID](/tB/Packages/Contributed/OLEGuids/OLECAUUID.md) -- a counted array of GUIDs
- [OLECLSID](/tB/Packages/Contributed/OLEGuids/OLECLSID.md) -- a class or interface identifier, with the layout of the Windows **GUID** structure
- [OLECONTROLINFO](/tB/Packages/Contributed/OLEGuids/OLECONTROLINFO.md) -- the keyboard mnemonic table of a control
- [OLEDISPPARAMS](/tB/Packages/Contributed/OLEGuids/OLEDISPPARAMS.md) -- the arguments of an **IDispatch.Invoke** call, with the layout of the Windows **DISPPARAMS** structure
- [OLEINPLACEFRAMEINFO](/tB/Packages/Contributed/OLEGuids/OLEINPLACEFRAMEINFO.md) -- accelerator information of an in-place frame
- [OLEPOINT](/tB/Packages/Contributed/OLEGuids/OLEPOINT.md) -- a point, with the layout of the Windows **POINT** structure
- [OLERECT](/tB/Packages/Contributed/OLEGuids/OLERECT.md) -- a rectangle, with the layout of the Windows **RECT** structure
- [OLESIZE](/tB/Packages/Contributed/OLEGuids/OLESIZE.md) -- a width and a height, with the layout of the Windows **SIZE** structure

## Test cases

The notes and warnings of this section are checked by the test cases in [OLEGuids-tests.twinproj](OLEGuids-tests.twinproj), a twinBASIC project. It uses OLEGuids as a [linked package](/Features/Packages/Linked.md#manual-management): put the package's `.twinpack` in `%APPDATA%\twinBASIC\packages`, then run the project, and each case prints whether it passes.
