lingma-proxy-compose/vendor/git.sr.ht/~jackmordaunt/go-toast/v2/ARCHITECTURE.md

Architecture

This document will attempt to explain how this code works.

Windows COM

Windows makes heavy use of it's COM api, (Component Object Model) which is a binary interface - allowing programs that agree on a memory layout in order to communicate.

COM apis are typically Object Oriented, and based on interfaces. This should be familiar to Go programmers, since Go includes interfaces as a core part of its language design and type system.

The difference being that in COM we don't get any runtime help, nice syntax or type safety. We get raw VTables and deal with raw memory.

You can think of COM as like working with a Go api that uses any (empty interface) everywhere and typeswitching is required to access methods file, ok := obj.(File).

Some languages like C++ have extensions that support COM and provide convenient wrappers for generating and using COM apis. Go does not. C also, does not.

However there is a package go-ole that allows us to call COM apis with some level of convenience - which we will use where possible. What go-ole does not expose is a way to implement a COM object in Go.

Interacting with COM objects in pure Go

In order to interact with COM objects we need to:

1. locate headers containing the VTable definitions
2. define vtables in Go that are compatable with those definitions
3. invoke the appropriate COM objects using our vtables and the syscall package

1. locate headers

Download Windows SDK via the Visual Studio installer. You will need to check "Desktop development with C++".

Once complete you can navigate to the SDK include directory.

In our case we needed Windows.ui.notifications.h, which contains the definitions of the types we want to call, and NotificationActivationCallback.h which contains the definition of INotificationActivationCallback which is the interface we need to implement.

2. define vtables in Go

The VTables are defined in C (mired in macros). We need to define compatible vtables in Go syntax so we can call the ones defined in the header.

COM objects are structured in a such a way that we want a parent struct who's first field is a pointer to the vtable struct. A full example is provided later, for now it we need something like this:

type Object struct {
  lpvtbl *ObjectVtbl
}
type ObjectVtbl struct {
  MethodOne uintptr
  MethdoTwo uintptr
  //...
}

3. invoke methods in Go

Using package syscall we can invoke these methods (provided the uintptr are valid) using syscal.SyscallN. Paramters and return values are defined in the C headers.

func (v *Object) One() error {
  hr, _, _ := syscall.SyscallN(uintptr(v))
  if hr != ole.S_OK {
    return ole.NewError(hr)
  }
  return nil
}

With that we can inoke methods on a COM object. This is how go-ole works.

Implementing a COM object in pure Go (no cgo!)

To do this we will need to allocate raw memory for the VTables (so that Go garbage collector doesn't interfere) and write our function pointers to the VTables.

Since these are not safe Go capabilities we will need the help of package syscall (on Windows).

Package syscall provides two very important functions:

1. NewProc - which loads a function from a DLL
2. NewCallback - which allocates a C-callable function pointer from a Go function

For the first part, we can load the Windows kernel api via kernel32.dll system dll, and pull out GlobalAlloc and GlobalFree using syscall.NewProc.

For the second part, we can use syscall.NewCallback to build a C-callable function pointer from a Go function and instantiate the VtTables with it. Caveat emptor: memory allocated by NewCallback is never released, and only 1024 callbacks are guaranteed to be allowed. This is why we only allocate the callbacks once on init.

Thus we can implement a COM object (invokable from C) like this:

// Initialize our kernel functions. 
var (
  kernel32   = windows.NewLazySystemDLL("kernel32.dll")
  procMalloc = kernel32.NewProc("GlobalAlloc")
  procFree   = kernel32.NewProc("GlobalFree")
)

// malloc allocates raw memory using the Windows kernel.
// In case of out of memory, the returned pointer will be nil.
// The memory is zeroed out to make sure we don't get garbage that looks like
// valid Go data types.
func malloc(size uintptr) unsafe.Pointer {
	hr, _, _ := procMalloc.Call(uintptr(GMEM_FIXED|GMEM_ZEROINIT), uintptr(size))
	if hr == 0 {
		return nil
	}
	return unsafe.Pointer(hr)
}

// free deallocates raw memory allocated by malloc.
func free(object unsafe.Pointer) {
	procFree.Call(uintptr(object))
}

// Object defines our object. 
// This is how COM objects are laid out in memory, where the first field is a pointer
// to a vtable, and the vtable's fields are pointers to functions. 
type Object struct {
  lpvtbl *ObjectVtbl // lpvtbl is a COM conventional name for this field. 
}

// ObjectVtbl defines the Vtable of our object. 
type ObjectVtbl struct {
  MethodOne   uintptr
  MethodTwo   uintptr
  MethodThree uintptr
}

// These methods are allocated once as package globals because Go will never reclaim the
// memory allocated for such callbacks. 
// 
// All arguments must be uintptr sized, and the return must be a uintptr as well. 
// 
// By convention, the first parameter is a pointer to the parent object. 
var (
  methodOne = syscall.NewCallback(func(this *Object) uintptr {
    fmt.Printf("methodOne invoked\n")
    return uintptr(0)
  })
  
  methodTwo = syscall.NewCallback(func(this *Object) uintptr {
    fmt.Printf("methodTwo invoked\n")
    return uintptr(0)
  })
  
  methodThree = syscall.NewCallback(func(this *Object) uintptr {
    fmt.Printf("methodThree invoked\n")
    return uintptr(0)
  })
)


func NewObject() *Object {
  // Allocate the parent object and the vtable. 
  obj := (*Object)(malloc(unsafe.Sizeof(Object{})))
  vtbl := (*ObjectVtbl)(malloc(unsafe.Sizeof(ObjectVtbl{})))

  // Initialize the vtable with our static callback implementations. 
  vtbl.MethodOne = methodOne
  vtbl.MethodTwo = methodTwo
  vtbl.MethodThree = methodThree
  
  // The returned object must be freed by GlobalFree. 
  object.lpvtbl = vtbl
  return obj
}

WinRT and Toast Notifications

For this package the vtables we need are located in various headers Windows.ui.notifications.h and NotificationActivationCallback.h and combase.h.

With all of the vtables replicated in Go as explained above we now need to interact with the Windows Runtime.

First we need to initialize the Windows Runtime with RoInitialize.

ole.RoInitialize(0)

Traditional COM uses GUIDs to identify objects and interfaces. WinRT uses strings (mapped to GUIDS at runtime).

To instantiate a WinRT COM object we invoke RoGetActivationFactory with the class string along with the interface GUID we expect to use.

CLSID_ToastNotification := "Windows.UI.Notifications.ToastNotification"
IID_IToastNotificationFactory := ole.NewGUID("{50AC103F-D235-4598-BBEF-98FE4D1A3AD4}")

factoryObject, err := ole.RoGetActivationFactory(CLSID_ToastNotification, IID_ToastNotificationFactory)
if err != nil {
	return nil, fmt.Errorf("getting activation factory: %w", err)
}

From there we can unsafe cast to our callback definition (ole doesn't provide direct access to the methods).

factory := (*IToastNotificationFactory)(unsafe.Pointer(factoryObject))
notification, err := factory.CreateToastNotification(xml)

Repeat this process per object we need to instantiate.

To generate a toast notification from XML with a callback we need to instantiate several COM objects:

1. INotificationActivationCallback our implementation to be invoked by the runtime
2. ClassFactory which can instantiate our INotificationActivationCallback implementation
3. XmlDocument to contain the xml content of the notification
4. XmlDocumentIO to provide an IO interface to the xml document (so we can write the xml to it)
5. Notification specifying the content of the notification
6. Notifier for showing notifications

Finally we register our class factory using CoRegisterClassObject so the runtime can call us back and then we invoke Notifier.Show passing in the Notification object to display the notification.

In addition to calling and implementing COM objects we need to manipulate registry state to tell the Windows Runtime metadata about our application.

1. register a CLSID (GUID) for our INotificationActivationCallback; this is how the runtime knows what object to ask for
2. optionally provide an icon and an activation executable to be invoked when our application is not running

With all of that correctly configured we can generate toast notifications on Windows in pure Go!