wmi

README

Windows Management Instrumentation

Description

This document at present details what would be needed to implement a new WMI/OLE interface for windows using golang.

Requirements

1. Package wmi provides a WQL interface to Windows WMI.

   Note: It interfaces with WMI on the local machine, therefore it only runs on Windows. It could interact with a remote Windows machine but that adds significant other issues.

2. This would replace go-ole (projects/ole) and projects/wmi with a pure Golang Equivalent.

Effort:

1. Creating a pure Golang equivalent of the Go-OLE and WMI projects would require designing modules that are capable of interfacing directly with the underlying Windows API in a clean, efficient manner without the need for CGO or other C++ code. This could be a complex task as it requires comprehensive knowledge of both the Windows API and the Golang language.

Components:

Here are the main components that would need to be developed:

1. OLE Automation/COM Interface:

   This will replace the Go-OLE functionality. It will allow Golang to interface with the Component Object Model (COM) in Windows, which is crucial for many types of automation and interaction with the operating system.

2. WMI Query Engine:

   This will replace the WMI functionality. It would need to send WMI queries and interpret the responses, providing a Golang-native way to access system information and settings.

3. Error Handling and Logging:

   This component is crucial for diagnosing issues and ensuring smooth operation.

4. Data Marshalling/Unmarshalling

   This component will ensure that data transferred between Golang and the Windows API is correctly interpreted and safely handled.

5. Testing and Validation

   This will ensure that the software is working as expected and that it provides the same functionality as the original projects.

+---------------------------+
|        Application        |
|  +---------------------+  |
|  |   OLE Automation    |  |
|  |   /COM Interface    |  |
|  +---------------------+  |
|  +---------------------+  |
|  |  WMI Query Engine   |  |
|  +---------------------+  |
|  +---------------------+  |
|  |   Error Handling &  |  |
|  |        Logging      |  |
|  +---------------------+  |
|  +---------------------+  |
|  |   Data Marshalling/ |  |
|  |     Unmarshalling   |  |
|  +---------------------+  |
|  +---------------------+  |
|  | Testing & Validation|  |
|  +---------------------+  |
+---------------------------+

Documentation

Overview

Package wmi provides a WQL interface for WMI on Windows.

Example code to print names of running processes:

type Win32_Process struct {
	Name string
}

func main() {
	var dst []Win32_Process
	q := wmi.CreateQuery(&dst, "")
	err := wmi.Query(q, &dst)
	if err != nil {
		log.Fatal(err)
	}
	for i, v := range dst {
		println(i, v.Name)
	}
}

Index

• Constants
• Variables
• func CallMethod(connectServerArgs []interface{}, className, methodName string, ...) (int32, error)
• func CreateQuery(src interface{}, where string, class ...string) string
• func Query(query string, dst interface{}, connectServerArgs ...interface{}) error
• func QueryNamespace(query string, dst interface{}, namespace string) error
• type Client
  • func (c *Client) CallMethod(connectServerArgs []interface{}, className, methodName string, ...) (int32, error)
  • func (c *Client) Query(query string, dst interface{}, connectServerArgs ...interface{}) error
• type ErrFieldMismatch
  • func (e *ErrFieldMismatch) Error() string
• type SWbemServices
  • func InitializeSWbemServices(c *Client, connectServerArgs ...interface{}) (*SWbemServices, error)
  • func (s *SWbemServices) Close() error
  • func (s *SWbemServices) Query(query string, dst interface{}, connectServerArgs ...interface{}) error

Constants

const S_FALSE = 0x00000001

S_FALSE is returned by CoInitializeEx if it was already called on this thread.

Variables

var (
	ErrInvalidEntityType = fmt.Errorf("wmi: invalid entity type")
	// ErrNilCreateObject is the error returned if CreateObject returns nil even
	// if the error was nil.
	ErrNilCreateObject = fmt.Errorf("wmi: create object returned nil")
)

var DefaultClient = &Client{}

DefaultClient is the default Client and is used by Query, QueryNamespace, and CallMethod.

Functions

func CallMethod

func CallMethod(connectServerArgs []interface{}, className, methodName string, params []interface{}) (int32, error)

CallMethod calls a method named methodName on an instance of the class named className, with the given params.

CallMethod is a wrapper around DefaultClient.CallMethod.

func CreateQuery

func CreateQuery(src interface{}, where string, class ...string) string

CreateQuery returns a WQL query string that queries all columns of src. where is an optional string that is appended to the query, to be used with WHERE clauses. In such a case, the "WHERE" string should appear at the beginning. The wmi class is obtained by the name of the type. You can pass a optional class throught the variadic class parameter which is useful for anonymous structs.

func Query

func Query(query string, dst interface{}, connectServerArgs ...interface{}) error

Query runs the WQL query and appends the values to dst.

dst must have type *[]S or *[]*S, for some struct type S. Fields selected in the query must have the same name in dst. Supported types are all signed and unsigned integers, time.Time, string, bool, or a pointer to one of those. Array types are not supported.

By default, the local machine and default namespace are used. These can be changed using connectServerArgs. See https://docs.microsoft.com/en-us/windows/desktop/WmiSdk/swbemlocator-connectserver for details.

Query is a wrapper around DefaultClient.Query.

func QueryNamespace

func QueryNamespace(query string, dst interface{}, namespace string) error

QueryNamespace invokes Query with the given namespace on the local machine.

Types

type Client

type Client struct {
	// NonePtrZero specifies if nil values for fields which aren't pointers
	// should be returned as the field types zero value.
	//
	// Setting this to true allows stucts without pointer fields to be used
	// without the risk failure should a nil value returned from WMI.
	NonePtrZero bool

	// PtrNil specifies if nil values for pointer fields should be returned
	// as nil.
	//
	// Setting this to true will set pointer fields to nil where WMI
	// returned nil, otherwise the types zero value will be returned.
	PtrNil bool

	// AllowMissingFields specifies that struct fields not present in the
	// query result should not result in an error.
	//
	// Setting this to true allows custom queries to be used with full
	// struct definitions instead of having to define multiple structs.
	AllowMissingFields bool

	// SWbemServiceClient is an optional SWbemServices object that can be
	// initialized and then reused across multiple queries. If it is null
	// then the method will initialize a new temporary client each time.
	SWbemServicesClient *SWbemServices
}

A Client is an WMI query client.

Its zero value (DefaultClient) is a usable client.

func (*Client) CallMethod

func (c *Client) CallMethod(connectServerArgs []interface{}, className, methodName string, params []interface{}) (int32, error)

CallMethod calls a WMI method named methodName on an instance of the class named className. It passes in the arguments given in params. Use connectServerArgs to customize the machine and namespace; by default, the local machine and default namespace are used. See https://docs.microsoft.com/en-us/windows/desktop/WmiSdk/swbemlocator-connectserver for details.

func (*Client) Query

func (c *Client) Query(query string, dst interface{}, connectServerArgs ...interface{}) error

Query runs the WQL query and appends the values to dst.

dst must have type *[]S or *[]*S, for some struct type S. Fields selected in the query must have the same name in dst. Supported types are all signed and unsigned integers, time.Time, string, bool, or a pointer to one of those. Array types are not supported.

By default, the local machine and default namespace are used. These can be changed using connectServerArgs. See https://docs.microsoft.com/en-us/windows/desktop/WmiSdk/swbemlocator-connectserver for details.

type ErrFieldMismatch

type ErrFieldMismatch struct {
	StructType reflect.Type
	FieldName  string
	Reason     string
}

ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct. StructType is the type of the struct pointed to by the destination argument.

func (*ErrFieldMismatch) Error

func (e *ErrFieldMismatch) Error() string

type SWbemServices

type SWbemServices struct {
	// contains filtered or unexported fields
}

SWbemServices is used to access wmi. See https://msdn.microsoft.com/en-us/library/aa393719(v=vs.85).aspx

func InitializeSWbemServices

func InitializeSWbemServices(c *Client, connectServerArgs ...interface{}) (*SWbemServices, error)

InitializeSWbemServices will return a new SWbemServices object that can be used to query WMI

func (*SWbemServices) Close

func (s *SWbemServices) Close() error

Close will clear and release all of the SWbemServices resources

func (*SWbemServices) Query

func (s *SWbemServices) Query(query string, dst interface{}, connectServerArgs ...interface{}) error

Query runs the WQL query using a SWbemServices instance and appends the values to dst.

dst must have type *[]S or *[]*S, for some struct type S. Fields selected in the query must have the same name in dst. Supported types are all signed and unsigned integers, time.Time, string, bool, or a pointer to one of those. Array types are not supported.

By default, the local machine and default namespace are used. These can be changed using connectServerArgs. See http://msdn.microsoft.com/en-us/library/aa393720.aspx for details.