From bb628025f5bbb4298ba0036a101c6f6e3721d82d Mon Sep 17 00:00:00 2001
From: Kevin Parsons <kevpar@ntdev.microsoft.com>
Date: Thu, 13 Dec 2018 14:12:44 -0800
Subject: [PATCH] Clean up some types and comments

---
 etw/etw.go           |  7 +++++++
 etw/event.go         | 12 +++++++-----
 etw/eventmetadata.go |  2 +-
 etw/provider.go      | 20 +++++++++++++++++---
 etw/sample/sample.go |  4 ++--
 5 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/etw/etw.go b/etw/etw.go
index e60a8fa..da905ec 100644
--- a/etw/etw.go
+++ b/etw/etw.go
@@ -1,3 +1,10 @@
+// Package etw provides support for TraceLogging-based ETW (Event Tracing
+// for Windows). TraceLogging is a format of ETW events that are self-describing
+// (the event contains information on its own schema). This allows them to be
+// decoded without needing a separate manifest with event information. The
+// implementation here is based on the information found in
+// TraceLoggingProvider.h in the Windows SDK, which implements TraceLogging as a
+// set of C macros.
 package etw
 
 //go:generate go run $GOROOT/src/syscall/mksyscall_windows.go -output zsyscall_windows.go etw.go
diff --git a/etw/event.go b/etw/event.go
index 2a01d4f..bbf3172 100644
--- a/etw/event.go
+++ b/etw/event.go
@@ -5,10 +5,10 @@ package etw
 type Channel uint8
 
 const (
-	// ChannelTracelogging is the default channel for tracelogging events. It is
-	// not required to be used for tracelogging, but will prevent decoding
+	// ChannelTraceLogging is the default channel for TraceLogging events. It is
+	// not required to be used for TraceLogging, but will prevent decoding
 	// issues for these events on older operating systems.
-	ChannelTracelogging Channel = 11
+	ChannelTraceLogging Channel = 11
 )
 
 // Level represents the ETW logging level. There are several predefined levels
@@ -56,12 +56,14 @@ type EventDescriptor struct {
 }
 
 // NewEventDescriptor returns an EventDescriptor initialized for use with
-// tracelogging.
+// TraceLogging.
 func NewEventDescriptor() *EventDescriptor {
+	// Standard TraceLogging events default to the TraceLogging channel, and
+	// verbose level.
 	return &EventDescriptor{
 		id:      0,
 		version: 0,
-		Channel: ChannelTracelogging,
+		Channel: ChannelTraceLogging,
 		Level:   LevelVerbose,
 		Opcode:  0,
 		Task:    0,
diff --git a/etw/eventmetadata.go b/etw/eventmetadata.go
index e4813c9..39e9909 100644
--- a/etw/eventmetadata.go
+++ b/etw/eventmetadata.go
@@ -8,7 +8,7 @@ import (
 // InType indicates the type of data contained in the ETW event.
 type InType byte
 
-// Various InType definitions for tracelogging.
+// Various InType definitions for TraceLogging.
 const (
 	InTypeNull InType = iota
 	InTypeUnicodeString
diff --git a/etw/provider.go b/etw/provider.go
index 4c50278..6bb23e3 100644
--- a/etw/provider.go
+++ b/etw/provider.go
@@ -26,9 +26,23 @@ type Provider struct {
 
 type providerHandle windows.Handle
 
+// ProviderState informs the provider EnableCallback what action is being
+// performed.
+type ProviderState uint32
+
+const (
+	// ProviderStateDisable indicates the provider is being disabled.
+	ProviderStateDisable ProviderState = iota
+	// ProviderStateEnable indicates the provider is being enabled.
+	ProviderStateEnable
+	// ProviderStateCaptureState indicates the provider is having its current
+	// state snap-shotted.
+	ProviderStateCaptureState
+)
+
 // EnableCallback is the form of the callback function that receives provider
 // enable/disable notifications from ETW.
-type EnableCallback func(*windows.GUID, uint32, byte, uint64, uint64, uintptr)
+type EnableCallback func(*windows.GUID, ProviderState, Level, uint64, uint64, uintptr)
 
 type eventDataDescriptor struct {
 	ptr       uint64
@@ -49,9 +63,9 @@ func (descriptor *eventDataDescriptor) set(dataType eventDataDescriptorType, buf
 
 // NewProvider creates and registers a new provider.
 func NewProvider(name string, id *windows.GUID, callback EnableCallback) (*Provider, error) {
-	innerCallback := func(sourceID *windows.GUID, isEnabled uint32, level byte, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr, _ uintptr) uintptr {
+	innerCallback := func(sourceID *windows.GUID, state ProviderState, level Level, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr, _ uintptr) uintptr {
 		if callback != nil {
-			callback(sourceID, isEnabled, level, matchAnyKeyword, matchAllKeyword, filterData)
+			callback(sourceID, state, level, matchAnyKeyword, matchAllKeyword, filterData)
 		}
 		return 0
 	}
diff --git a/etw/sample/sample.go b/etw/sample/sample.go
index 46850dc..3088412 100644
--- a/etw/sample/sample.go
+++ b/etw/sample/sample.go
@@ -12,8 +12,8 @@ import (
 	"golang.org/x/sys/windows"
 )
 
-func callback(sourceID *windows.GUID, isEnabled uint32, level byte, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr) {
-	fmt.Printf("Callback: isEnabled=%d, level=%d, matchAnyKeyword=%d\n", isEnabled, level, matchAnyKeyword)
+func callback(sourceID *windows.GUID, state etw.ProviderState, level etw.Level, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr) {
+	fmt.Printf("Callback: isEnabled=%d, level=%d, matchAnyKeyword=%d\n", state, level, matchAnyKeyword)
 }
 
 func main() {