winim/com

This module adds Windows COM support for Winim. It allows Nim to interact with COM objects like a scripting language. For example:

comScript:
  var dict = CreateObject("Scripting.Dictionary")
  dict.add("a", "the")
  dict.add("b", item:="quick")
  dict.add(item:="fox", key:="c")
  dict.item(key:="c") = "dog"
  for key in dict:
    echo key, " => ", dict.item(key)

This module introduces two new types for dealing with COM objects: "com" and "variant". In summary, CreateObject() and GetObject() return a "com" value, and any input/output of a COM method should be a "variant" value.

Most Nim data types and Winim string types can be converted to/from "variant" values. The conversion is usually automatic. However, explicit conversion is also supported.

proc toVariant[T](x: T): variant
proc fromVariant[T](x: variant): T
  
  # Supported type:
  #   char|string|cstring|mstring|wstring|BSTR
  #   bool|enum|SomeInteger|SomeReal
  #   com|variant|VARIANT|ptr IUnknown|ptr IDispatch|pointer
  #   SYSTEMTIME|FILETIME
  #   1D~3D array|seq|COMBinary

The COMBinary type can help deal with binary data. For example:

var input = "binary\0string\0test\0"
var v = toVariant(COMBinary input)
var output = string fromVariant[COMBinary](v)
assert input == output

Imports

winimbase, utils, winstr, core, shell, ole

Types

com = ref object
  when hasTraceTable:
IDispatch wrapper. 
COMArray = seq[variant]
Generic one-dimensional Automation array. 
COMArray1D = seq[variant]
One-dimensional Automation array. 
COMArray2D = seq[seq[variant]]
Two-dimensional Automation array. 
COMArray3D = seq[seq[seq[variant]]]
Three-dimensional Automation array. 
COMBinary = distinct string
Binary bytes transported as VT_ARRAY|VT_UI1. 
COMError = object of CatchableError
  hresult*: HRESULT
Base error for COM. 
comEventHandler = proc (self: com; name: string; params: varargs[variant]): variant
COMException = object of COMError
COM dispatch exception. 
variant = ref object
  when hasTraceTable:
VARIANT wrapper. 
VariantConversionError = object of ValueError
Raised when a VARIANT conversion fails.

Procs

proc `$`(x: variant): string {.inline,
                               ...raises: [VariantConversionError, COMError],
                               tags: [], forbids: [].}
proc `<`(x, y: COMBinary): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `<=`(x, y: COMBinary): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `==`(x, y: COMBinary): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `[]`(self: variant; name: string): variant {.
    ...raises: [Exception, VariantConversionError, COMError, COMException],
    tags: [RootEffect], forbids: [].}
proc adoptCom(x: var ptr IDispatch): com {....raises: [COMError], tags: [],
    forbids: [].}
Takes ownership of one IDispatch reference and clears x. 
proc adoptVariant(x: var VARIANT): variant {....raises: [COMError], tags: [],
    forbids: [].}
Takes ownership of a raw VARIANT and resets x to VT_EMPTY. 
proc call(self: com; name: string; vargs: varargs[variant, toVariant]): variant {.
    discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc call(self: com; name: string; vargs: varargs[variant, toVariant];
          kwargs: openArray[(string, variant)]): variant {.discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc cmp(x, y: COMBinary): int {.borrow, ...raises: [], tags: [], forbids: [].}
proc COM_FullRelease() {....raises: [], tags: [], forbids: [].}

Releases all COM wrappers tracked on the current thread.

Normally the memory manager releases wrappers. Some COM servers, such as Excel.Application, can keep a process alive when cycles or outstanding references survive GC_fullCollect; this procedure provides deterministic cleanup for that case.

The hidden per-thread COM initialization remains active until the thread exits, avoiding delayed-destructor use-after-uninitialize hazards. Use -d:notrace to disable wrapper tracking.

proc connect(self: com; handler: comEventHandler; riid: REFIID = nil): DWORD {.
    discardable, ...raises: [COMError, Exception], tags: [RootEffect], forbids: [].}
Connects a COM event handler and returns its connection cookie. The handler is a user-defined proc to receive the COM event. comEventHandler is defined as:
type comEventHandler = proc(self: com, name: string, params: varargs[variant]): variant
proc copy(x: com): com {.inline, ...raises: [COMError, Exception],
                         tags: [RootEffect], forbids: [].}
Copies a COM wrapper by adding one IDispatch reference. 
proc copy(x: variant): variant {....raises: [VariantConversionError], tags: [],
                                 forbids: [].}
Copies a variant. 
proc CreateObject(progId: string): com {....raises: [COMError, Exception],
    tags: [RootEffect], forbids: [].}
Creates a COM object in the current thread's automatically initialized apartment. Raises COMError for invalid class identifiers or activation failures. 
proc desc(e: ref COMError): string {....raises: [], tags: [], forbids: [].}
Returns the Windows message for e.hresult. 
proc desc(self: com; name: string): string {....raises: [COMError, Exception],
    tags: [RootEffect], forbids: [].}
Gets the description (including the name and arguments) for the specified method. 
proc disconnect(self: com; cookie: DWORD; riid: REFIID = nil): bool {.
    discardable, ...raises: [COMError, Exception], tags: [RootEffect], forbids: [].}
Disconnects an event cookie. 
proc fromVariant[T](x: variant): T
proc get(self: com; name: string; vargs: varargs[variant, toVariant]): variant {.
    discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc get(self: com; name: string; vargs: varargs[variant, toVariant];
         kwargs: openArray[(string, variant)]): variant {.discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc getCurrentCOMError(): ref COMError {.inline, ...raises: [], tags: [],
    forbids: [].}
Returns the current exception cast to COMError. 
proc GetObject(file: string; progId: string = ""): com {.
    ...raises: [COMError, Exception], tags: [RootEffect], forbids: [].}
Retrieves a COM object from an active object, file, or moniker. The current thread is initialized automatically. Failures raise COMError. 
proc high(s: COMBinary): int {.borrow, ...raises: [], tags: [], forbids: [].}
proc isNull(x: variant): bool {.inline, ...raises: [], tags: [], forbids: [].}
Returns whether the wrapper represents nil, VT_EMPTY, VT_NULL, or a nil interface. 
proc len(x: COMBinary): int {.borrow, ...raises: [], tags: [], forbids: [].}
proc low(s: COMBinary): int {.borrow, ...raises: [], tags: [], forbids: [].}
proc newCom(file, progId: string): com {.inline, ...raises: [COMError, Exception],
    tags: [RootEffect], forbids: [].}
Alias for GetObject(file, progId). 
proc newCom(progId: string): com {.inline, ...raises: [COMError, Exception],
                                   tags: [RootEffect], forbids: [].}
Alias for CreateObject. 
proc newCom(x: ptr IDispatch): com {....raises: [COMError, Exception],
                                     tags: [RootEffect], forbids: [].}
Copies a borrowed IDispatch pointer and calls AddRef on it. 
proc newVariant(x: VARIANT): variant {....raises: [COMError, VariantConversionError],
                                       tags: [], forbids: [].}
Copies a raw VARIANT. 
proc rawType(x: variant): VARTYPE {.inline, ...raises: [], tags: [], forbids: [].}
Returns the raw VARTYPE. 
proc rawTypeDesc(x: variant): string {....raises: [], tags: [], forbids: [].}
Returns a readable raw VARTYPE description. 
proc set(self: com; name: string; vargs: varargs[variant, toVariant]): variant {.
    discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc set(self: com; name: string; vargs: varargs[variant, toVariant];
         kwargs: openArray[(string, variant)]): variant {.discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc setRef(self: com; name: string; vargs: varargs[variant, toVariant]): variant {.
    discardable, inline,
    ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc setRef(self: com; name: string; vargs: varargs[variant, toVariant];
            kwargs: openArray[(string, variant)]): variant {.discardable,
    inline, ...raises: [COMError, Exception, VariantConversionError, COMException],
    tags: [RootEffect], forbids: [].}
proc substr(s: COMBinary; first = 0): COMBinary {.borrow, ...raises: [], tags: [],
    forbids: [].}
proc substr(s: COMBinary; first, last: int): COMBinary {.borrow, ...raises: [],
    tags: [], forbids: [].}
proc toVariant(x: bool): variant {....raises: [], tags: [], forbids: [].}
proc toVariant(x: BSTR): variant {....raises: [VariantConversionError], tags: [],
                                   forbids: [].}
proc toVariant(x: char): variant {....raises: [], tags: [], forbids: [].}
proc toVariant(x: com): variant {....raises: [Exception], tags: [RootEffect],
                                  forbids: [].}
proc toVariant(x: COMBinary): variant {....raises: [VariantConversionError],
                                        tags: [], forbids: [].}
proc toVariant(x: FILETIME): variant {....raises: [VariantConversionError],
                                       tags: [], forbids: [].}
proc toVariant(x: pointer): variant {....raises: [], tags: [], forbids: [].}
proc toVariant(x: ptr IDispatch): variant {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
proc toVariant(x: ptr IUnknown): variant {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
proc toVariant(x: ptr SomeInteger | ptr SomeFloat | ptr char | ptr bool |
    ptr BSTR): variant
proc toVariant(x: SomeFloat): variant
proc toVariant(x: SomeInteger | enum): variant
proc toVariant(x: string | cstring | mstring): variant
proc toVariant(x: SYSTEMTIME): variant {....raises: [VariantConversionError],
    tags: [], forbids: [].}
proc toVariant(x: VARIANT): variant {....raises: [VariantConversionError],
                                      tags: [], forbids: [].}
proc toVariant(x: variant): variant {....raises: [VariantConversionError],
                                      tags: [], forbids: [].}
proc toVariant(x: wstring): variant {....raises: [VariantConversionError],
                                      tags: [], forbids: [].}
proc toVariant[T](x: openArray[T]; vt: VARENUM = VT_VARIANT): variant
proc unwrap(x: com): ptr IDispatch {.inline, ...raises: [], tags: [], forbids: [].}
Returns a borrowed IDispatch pointer without transferring ownership. 
proc unwrap(x: variant): VARIANT {.inline, ...raises: [], tags: [], forbids: [].}
Returns a borrowed raw VARIANT view without transferring ownership. 
proc wrap(x: ptr IDispatch): com {.inline, ...deprecated: "use `newCom` for a borrowed pointer or `adoptCom` for an owned pointer",
                                   raises: [COMError, Exception],
                                   tags: [RootEffect], forbids: [].}
Deprecated: use `newCom` for a borrowed pointer or `adoptCom` for an owned pointer
Deprecated compatibility wrapper for newCom. 
proc wrap(x: VARIANT): variant {.inline, ...deprecated: "use `newVariant` to copy or `adoptVariant` to transfer ownership",
                                 raises: [], tags: [], forbids: [].}
Deprecated: use `newVariant` to copy or `adoptVariant` to transfer ownership
Deprecated compatibility wrapper; retains the historical raw ownership behavior.

Iterators

iterator items(x: com): variant {....raises: [COMError, Exception,
    VariantConversionError], tags: [RootEffect], forbids: [].}
iterator items(x: variant): variant {....raises: [Exception,
    VariantConversionError, COMError], tags: [RootEffect], forbids: [].}

Converters

converter variantConverterToBool(x: variant): bool {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToChar(x: variant): char {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToCom(x: variant): com {.
    ...raises: [VariantConversionError, COMError, Exception], tags: [RootEffect],
    forbids: [].}
converter variantConverterToCOMArray1D(x: variant): COMArray1D {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToCOMArray2D(x: variant): COMArray2D {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToCOMArray3D(x: variant): COMArray3D {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToCOMBinary(x: variant): COMBinary {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToCString(x: variant): cstring {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToFILETIME(x: variant): FILETIME {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToFloat32(x: variant): float32 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToFloat64(x: variant): float64 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToIDispatch(x: variant): ptr IDispatch {.
    ...raises: [VariantConversionError, COMError, Exception], tags: [RootEffect],
    forbids: [].}
converter variantConverterToInt(x: variant): int {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToInt8(x: variant): int8 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToInt16(x: variant): int16 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToInt32(x: variant): int32 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToInt64(x: variant): int64 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToIUnknown(x: variant): ptr IUnknown {.
    ...raises: [VariantConversionError, COMError, Exception], tags: [RootEffect],
    forbids: [].}
converter variantConverterToMString(x: variant): mstring {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToPointer(x: variant): pointer {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToString(x: variant): string {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToSYSTEMTIME(x: variant): SYSTEMTIME {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToUInt(x: variant): uint {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToUInt8(x: variant): uint8 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToUInt16(x: variant): uint16 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToUInt32(x: variant): uint32 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToUInt64(x: variant): uint64 {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}
converter variantConverterToVARIANT(x: variant): VARIANT {.
    ...raises: [VariantConversionError], tags: [], forbids: [].}
converter variantConverterToWString(x: variant): wstring {.
    ...raises: [VariantConversionError, COMError], tags: [], forbids: [].}

Macros

macro `.`(self: com; name: untyped; vargs: varargs[untyped]): untyped
macro `.=`(self: com; name: untyped; vargs: varargs[untyped]): untyped
macro comScript(x: untyped): untyped
Nim's dot operators .= only allow "a.b = c". With this macro, "a.b(c, d) = e" is allowed. Some assignments require this macro to work. Moreover, this macro also translates named arguments to table constructor syntax which functions related to methods and properties can accept (here we use := as assignment to avoid syntax conflict). For example:
comScript:
  dict.item("c") = "dog"
  dict.add(item:="fox", key:="c")
  excel.activeSheet.cells(1, 1) = "text"
  excel.activeSheet.range(cell1:="A1") = "text"

Templates

template `.`(self: variant; name: untyped): variant
template `[]`(self: com; name: string): variant
template `[]=`(self: com; name: string; v: untyped)

Made with Nim.