comutil

README

comutil

The comutil library provides additional API and type support for interacting with the component object model runtime in Windows, beyond that which is supplied by the go-ole library.

In particular, this library enables the creation of COM instances that communicate directly with remote servers.

This library is a work in progress. The API it provides is liable to be modified as additional features are added. It is possible that it may someday be merged into go-ole or into another library if it seems appropriate.

Documentation

Index

• Variables
• func BuildVarArrayStr(elements ...string) (v *ole.VARIANT, err error)
• func CreateInstanceEx(clsid uuid.UUID, context uint, serverInfo *CoServerInfo, results []MultiQI) (err error)
• func CreateObject(clsid uuid.UUID, iid uuid.UUID) (iface *ole.IUnknown, err error)
• func CreateRemoteObject(server string, clsid uuid.UUID, iid uuid.UUID) (iface *ole.IUnknown, err error)
• func GUID(id uuid.UUID) *ole.GUID
• func IIDFromString(value string) (iid *ole.GUID, err error)
• func SafeArrayCopy(original *ole.SafeArray) (duplicate *ole.SafeArray, err error)
• func SafeArrayCreateVector(variantType ole.VT, lowerBound int32, length uint32) (safearray *ole.SafeArray, err error)
• func SafeArrayFromStringSlice(slice []string) *ole.SafeArray
• func SafeArrayGetDim(safearray *ole.SafeArray) (dimensions uint32, err error)
• func SafeArrayGetElement(safearray *ole.SafeArray, index int32, element unsafe.Pointer) (err error)
• func SafeArrayPutElement(safearray *ole.SafeArray, index int32, element unsafe.Pointer) (err error)
• func SafeArrayToConcreteSlice(array *ole.SafeArrayConversion) (value interface{}, err error)
• func SafeArrayToSlice(array *ole.SafeArrayConversion) (value interface{}, err error)
• func SafeArrayToVariantSlice(array *ole.SafeArrayConversion) (values []interface{}, err error)
• func VariantToValue(variant *ole.VARIANT) (value interface{}, err error)
• type CoAuthIdentity
• type CoAuthInfo
• type CoServerInfo
• type MultiQI

Variables

var (
	// ErrCreationFailed is returned when instance creation fails for an
	// unspecified reason. This generally means that NULL was returned from
	// CoCreateInstanceEx but an HRESULT value of S_OK was returned instead of a
	// proper error code. Under normal circumstances with correctly written
	// component object model servers this error should never occur.
	ErrCreationFailed = errors.New("unable to create interface instance")

	// ErrMultiDimArray is returned when a safe array contains more than one
	// one dimension. Multi-dimensional array parsing is not currently supported.
	ErrMultiDimArray = errors.New("attribute contains a multi-dimensional array of values")

	// ErrUnsupportedArray is returned when members of a safe array members are
	// supported for type conversion.
	ErrUnsupportedArray = errors.New("unsupported safe array member type")

	// ErrVariantArray is returned when members of a safe array members were not
	// expected to variants but are.
	ErrVariantArray = errors.New("attribute contains variant array members")

	// ErrNonVariantArray is returned when members of a safe array members were
	// expected to variants but are not.
	ErrNonVariantArray = errors.New("attribute contains non-variant array members")
)

var (
	ErrUnsupported = errors.New("call is unsupported on this platform")
)

Functions

func BuildVarArrayStr

func BuildVarArrayStr(elements ...string) (v *ole.VARIANT, err error)

func CreateInstanceEx

func CreateInstanceEx(clsid uuid.UUID, context uint, serverInfo *CoServerInfo, results []MultiQI) (err error)

func CreateObject

func CreateObject(clsid uuid.UUID, iid uuid.UUID) (iface *ole.IUnknown, err error)

CreateObject supports local creation of a single component object model interface. The class identified by the given class ID will be asked to create an instance of the supplied interface ID. If creation fails an error will be returned.

It is the caller's responsibility to cast the returned interface to the correct type. This is typically done with an unsafe pointer cast.

func CreateRemoteObject

func CreateRemoteObject(server string, clsid uuid.UUID, iid uuid.UUID) (iface *ole.IUnknown, err error)

CreateRemoteObject supports remote creation of a single component object model interface. The class identified by the given class ID will be asked to create an instance of the supplied interface ID. If creation fails an error will be returned.

If the provided server name is empty, this function will create an instance on the local machine. It is then the same as calling CreateObject.

It is the caller's responsibility to cast the returned interface to the correct type. This is typically done with an unsafe pointer cast.

func GUID

func GUID(id uuid.UUID) *ole.GUID

GUID converts the given uuid to a Windows-style guid that can be used by api calls. This is often necessary to ensure correct byte order.

func IIDFromString

func IIDFromString(value string) (iid *ole.GUID, err error)

func SafeArrayCopy

func SafeArrayCopy(original *ole.SafeArray) (duplicate *ole.SafeArray, err error)

func SafeArrayCreateVector

func SafeArrayCreateVector(variantType ole.VT, lowerBound int32, length uint32) (safearray *ole.SafeArray, err error)

func SafeArrayFromStringSlice

func SafeArrayFromStringSlice(slice []string) *ole.SafeArray

SafeArrayFromStringSlice creates a SafeArray from the given slice of strings.

See http://www.roblocher.com/whitepapers/oletypes.html

func SafeArrayGetDim

func SafeArrayGetDim(safearray *ole.SafeArray) (dimensions uint32, err error)

func SafeArrayGetElement

func SafeArrayGetElement(safearray *ole.SafeArray, index int32, element unsafe.Pointer) (err error)

func SafeArrayPutElement

func SafeArrayPutElement(safearray *ole.SafeArray, index int32, element unsafe.Pointer) (err error)

func SafeArrayToConcreteSlice

func SafeArrayToConcreteSlice(array *ole.SafeArrayConversion) (value interface{}, err error)

SafeArrayToConcreteSlice converts the given non-variant array to a native Go representation. A slice of appropriately typed elements will be returned.

If the array contains variant elements an error will be returned.

Only arrays of integers and bytes are supported. Support for additional types may be added in the future.

func SafeArrayToSlice

func SafeArrayToSlice(array *ole.SafeArrayConversion) (value interface{}, err error)

SafeArrayToSlice converts the given array to a native Go representation. A slice of appropriately typed elements will be returned.

If the array contains IUnknown or IDispatch members, it is the caller's responsibility to release them.

func SafeArrayToVariantSlice

func SafeArrayToVariantSlice(array *ole.SafeArrayConversion) (values []interface{}, err error)

SafeArrayToVariantSlice converts the given variant array to a native Go representation. A slice of interface{} members will be returned.

If the array does not contain variant members an error will be returned.

If the array contains IUnknown or IDispatch members, it is the caller's responsibility to release them.

func VariantToValue

func VariantToValue(variant *ole.VARIANT) (value interface{}, err error)

VariantToValue attempts to convert the given variant to a native Go representation.

If the value contains an IUnknown or IDispatch interface, it is the caller's responsibility to release it.

If the value contains an an array with IUnknown or IDispatch members, it is the caller's responsibility to release them.

Types

type CoAuthIdentity

type CoAuthIdentity struct {
	User           *uint16
	UserLength     uint32
	Domain         *uint16
	DomainLength   uint32
	Password       *uint16
	PasswordLength uint32
	Flags          uint32
}

CoAuthIdentity represents the COAUTHITDENTIY structure expected by the Windows COM api. It is a low-level structure that is used behind the scenes by the object creation functions.

MSDN: https://msdn.microsoft.com/library/ms693358

type CoAuthInfo

type CoAuthInfo struct {
	AuthenticationService uint32
	AuthorizationService  uint32
	ServerPrincipalName   *int16
	AuthenticationLevel   uint32
	ImpersonationLevel    uint32
	AuthIdentityData      *CoAuthIdentity
	Capabilities          uint32
}

CoAuthInfo represents the COAUTHINFO structure expected by the Windows COM api. It is a low-level structure that is used behind the scenes by the object creation functions.

MSDN: https://msdn.microsoft.com/library/ms688552

type CoServerInfo

type CoServerInfo struct {
	Name     *int16
	AuthInfo *CoAuthInfo
	// contains filtered or unexported fields
}

CoServerInfo represents the COSERVERINFO structure expected by the Windows COM api. It is a low-level structure that is used behind the scenes by the object creation functions.

MSDN: https://msdn.microsoft.com/library/ms687322

type MultiQI

type MultiQI struct {
	IID       *ole.GUID
	Interface *ole.IUnknown
	HR        uintptr
}

MultiQI represents the MULTI_QI structure expected by the Windows COM api. It is a low-level structure that is used behind the scenes by the object creation functions.

MSDN: https://msdn.microsoft.com/library/ms687289