go-toast

ARCHITECTURE.md (9155B)

---

 # Architecture
 
 This document will attempt to explain how this code works. 
 
 ## Windows COM 
 
 Windows makes heavy use of it's [COM api](https://en.wikipedia.org/wiki/Component_Object_Model), 
 (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](https://en.wikipedia.org/wiki/Virtual_method_table) 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](https://visualstudio.microsoft.com/downloads). 
 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:
 
 ```go
 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. 
 
 ```go
 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:
 
 ```go
 
 // 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`. 
 
 ```go
 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. 
 
 
 ```go
 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).
 
 ```go
 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 
 1. `ClassFactory` which can instantiate our `INotificationActivationCallback` implementation
 1. `XmlDocument` to contain the xml content of the notification
 1. `XmlDocumentIO` to provide an IO interface to the xml document (so we can write the xml to it)
 1. `Notification` specifying the content of the notification
 1. `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!