WeaveLink

WeaveLink is a Windows COM API that can be used for communication between Weave and another application or web page. See this page for more information about installing and testing WeaveLink.

The WeaveLink COM API provides the following functionality:

Locate an existing browser instance running Weave
Create a new browser running Weave if an existing one can't be found
Bring the Weave browser to the front of other windows
Execute an action in the Weave client and return the results
Listen for events fired by the Weave client

As you can see the actual functionality provided by the API is very limited, with most of the actual work being performed by the Weave client running in the browser. This simplified API means that new functions can be called without the need to upgrade the WeaveLink components on every client PC.

Unfortunately this also means that a certain amount of boiler plate code needs to be added to actually make us of this API, work is underway to provide a higher level API in Weave 2.4 that sits on top of the WeaveLink API and provides functionality in terms of entities, maps, etc, but this page documents the WeaveLink COM API.

Getting a link to the Weave client

Unless indicated otherwise all code samples below were written and tested using Visual Basic in Visual Studio 2005.

But it's possible to use the WeaveLink COM API in older and newer version of Visual Basic and Visual Studio, as well as Windows Scripting Host and even VBScript or JavaScript within a web page.

The first step when communicating with the Weave client is to create a WeaveLink.ILink object.

The basic interface for this class is contained in WeaveLink.dll with either WeaveLinkImpl.exe or WeaveLinkDebug.exe providing the implementation.

If you have a Weave instance available then WeaveLinkImpl.exe should be used, if you don't then WeaveLinkDebug.exe can be used to provide a test harness.

This class provides a way to:

Obtain a reference to a Weave client
Check what version of the WeaveLink API is being used (useful for weakly types languages)
Obtain a reference to a Sink that can used to respond to events triggered in the Weave client

So to create the ILink object you would use something like the following


Dim link As WeaveLink.ILink
link = CreateObject("Weave.Link")

Then once you have a link you can obtain a reference to a Weave client by using its Client method.


Dim client As WeaveLink.IClient
client = link.Client("Weave HTML Client", "http://wrath:8080/weave/main.html")

This will locate a running instance of Internet Explorer that contains the Weave client based on the window title given as the first parameter, or start a new instance using the second parameter if it can't find one.

Communicating with the Weave client

Once we have a reference to the client we can then call actions that are provided by the JavaScript embedded in the client by using the Send() method of the IClient class.

The Send() method takes an action id and a parameter string, in JSON format, and passes that to the Weave client and returns the results of that action in a Result object.

The Result class provides an Error Boolean property that indicates if there was an error executing the action, if the Error property is true then the operation failed and the Value property of the Result will be a String describing the problem. If the Error property is false then the Value property will return an object that is the actual response from the action.


Dim response As WeaveLink.Result

response = client.Send("com.cohga.GetActiveEntity", "{}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
Else
    Dim entity As String
    entity = response.Value
End If


response = client.Send("com.cohga.SetActiveEntity", "{entity: 'property'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

From here it's just a matter of knowing what actions are available, what parameters they require and what they return.

Actions available in Weave 2.3

com.cohga.ZoomSelection

Parameters

name	type	optional	description

name	type	optional	description
entity	string	yes	The id of the entity who's selection should be zoomed to, the active entity will be used if this parameter isn't supplied

Zoom to the selection of the property entity


response = client.Send("com.cohga.ZoomSelection", "{entity: 'property'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

Zoom to the current selection of the active entity


response = client.Send("com.cohga.ZoomSelection", "{}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

com.cohga.SetSelection

Parameters

name	type	optional	description

name	type	optional	description
entity	string	no	The id of the entity who's selection should be updated
ids	object or object[]	no	The id or array of ids to update the selection with
operator	'REPLACE', 'ADD', 'REMOVE', 'REFINE', 'CLEAR'	yes	Determines what will be done with the selection set relative to the current selection, the default if not set is 'REPLACE'
clearOthers	boolean	yes	If `true` the selections for all other entities will be cleared during the processing of this action, if `false` or not set then other entities selections will be untouched
active	boolean	yes	If `true` or not set then the active entity will also be changed to this entity, if set to `false` then the active entity won't be changed
zoom	boolean	yes	If `true` or not set then the map will also zoom to the new selection extent, if set to `false` then the map extent won't be changed


response = client.Send("com.cohga.SetSelection", "{entity: 'property', ids: [11000, 11001], clearOthers: true}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If


response = client.Send("com.cohga.SetSelection", "{entity: 'roads', ids: ['PENNY LANE', 'BOURBON STREET', 'ELECTRIC AVENUE'], active: false, zoom: false, operator: 'ADD'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

com.cohga.GetSelection

Parameters

name	type	optional	description

name	type	optional	description
entity	String or String[]	yes	The id, or array of id's, of the entity who's selection should be retrieved, if not set then all entities that the user has access to will be returned
returnids	Boolean	yes	If `true` or not set then the current list of id will also be returned, if set to `false` then only the current size of the selection will be returned

Return

name	type	optional	description

name	type	optional	description
entity	String	no	The id of the entity who's selection is being returned
size	Integer	no	The number of unique identifiers currently selected for the entity
ids	Object[]	yes	The individual id's for the entity, not included if `returnids` is set to `false`

Regardless of how many entities are requested this action will always return an array of object of the above format.


response = client.Send("com.cohga.GetSelection", "{entity: 'property', returnids: false}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If


property 2


response = client.Send("com.cohga.GetSelection", "{entity: ['property', 'roads'], returnids: false}")
    If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If


property 2
roads 6


response = client.Send("com.cohga.GetSelection", "{returnids: false}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If


buildings 0
property 2
busstops 0
roads 6
drainage 0
development_applications 0
hydrants 0
suburbs 0


response = client.Send("com.cohga.GetSelection", "{entity: 'roads'}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
        Dim ids As Object
        Dim idcount As Integer
        Dim j As Integer
        ids = CallByName(v, "ids", CallType.Get)
        idcount = CallByName(ids, "length", CallType.Get)
        For j = 0 To idcount - 1
            Debug.Print(CallByName(ids, j, CallType.Get))
        Next
    Next
End If


roads 6
ABBEY ROAD
BOURBON STREET
LONELY AVENUE
PENNY LANE
ELECTRIC AVENUE
GASOLINE ALLEY

com.cohga.SetActiveEntity

com.cohga.GetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

Actions available in Weave 2.4

com.cohga.ZoomSelection

com.cohga.SetSelection

com.cohga.GetSelection

com.cohga.SetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

com.cohga.ClearSelection

com.cohga.GetActiveEntity

com.cohga.GetEntities

com.cohga.GetEntity

com.cohga.GetExtent

com.cohga.SetExtent

com.cohga.SetLocation

com.cohga.GetLocation

com.cohga.GetScales

com.cohga.GetVersion

Parameters

name	type	optional	description

name	type	optional	description
item	string or string[]	yes	The id or, array of id's, of the item who's version should be return, if null then version number for all components will be returned

Return

name	type	optional	description

name	type	optional	description
item	String	no	The name of the item
version	String	no	The version string, format will always be major[.minor[.release]], where major, minor and release will be numeric and minor and release are optional
major	Integer	no	The major version number of the item
minor	Integer	yes	The minor version number of the item
release	Integer	yes	The release version number of the components

If one item is requested then only 1 object of this format will be returned, if multiple items (even if only 1 item requested finds a match) or all items are requested then an array of objects of this format will be returned.


response = client.Send("com.cohga.GetVersion", "{item: 'weave'}")
If Not response.Error Then
    Dim v As Object
    v = response.Value
    Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
End If


weave 2.4 2 4


response = client.Send("com.cohga.GetVersion", "{item: ['client', 'weave']}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
    Next
End If


client 2.1.1 2 1 1
weave 2.4 2 4


response = client.Send("com.cohga.GetVersion")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
    Next
End If


weave 2.4 2 4
client 2.1.1 2 1 1
interop 2.1.0 2 1 0

Third Party Application Integration

WeaveLink

Getting a link to the Weave client

Communicating with the Weave client

Actions available in Weave 2.3

com.cohga.ZoomSelection

com.cohga.SetSelection

com.cohga.GetSelection

com.cohga.SetActiveEntity

com.cohga.GetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

Actions available in Weave 2.4

com.cohga.ZoomSelection

com.cohga.SetSelection

com.cohga.GetSelection

com.cohga.SetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

com.cohga.ClearSelection

com.cohga.GetActiveEntity

com.cohga.GetEntities

com.cohga.GetEntity

com.cohga.GetExtent

com.cohga.SetExtent

com.cohga.SetLocation

com.cohga.GetLocation

com.cohga.GetScales

com.cohga.GetVersion