wmi

README

wmi

Package wmi provides a WQL interface to Windows WMI.

Note: It interfaces with WMI on the local machine, therefore it only runs on Windows.

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 = errors.New("wmi: invalid entity type")
	// ErrNilCreateObject is the error returned if CreateObject returns nil even
	// if the error was nil.
	ErrNilCreateObject = errors.New("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.