comutil

package module
v0.0.0-...-a19f1d8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 16, 2023 License: MIT Imports: 5 Imported by: 6

README

comutil GoDoc

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

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.