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
WeaveLinkAPI is being used (useful for weakly types languages) - Obtain a reference to a
Sinkthat 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 |
|---|---|---|---|
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 |
|---|---|---|---|
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 |
active |
boolean |
yes |
If |
zoom |
boolean |
yes |
If |
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 |
|---|---|---|---|
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 |
Return
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 |
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 |
|---|---|---|---|
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 |
|---|---|---|---|
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