Set ConnexionHandlers aka callback function pointers

First you have to tell the driver which callback functions it has to use, when broadcasting device-events like axis value changes, pressed button Ids, and configuration changes. The responsible function for this is:

int16_t SetConnexionHandlers(ConnexionMessageHandlerProc messageHandler, ConnexionAddedHandlerProc addedHandler, ConnexionRemovedHandlerProc removedHandler, bool useSeparateThread);

func SetConnexionHandlers(messageHandler: ConnexionMessageHandlerProc!, _ addedHandler: ConnexionAddedHandlerProc!, _ removedHandler: ConnexionRemovedHandlerProc!, _ useSeparateThread: Bool) -> Int16

As you can see it uses custom function types, also found in the ConnexionClientAPI.h file. If you look closer, you’ll notice that it calls for function pointers. As with Swift 2.1 there is an concept for this to bridge the gap between C and Swift, but sadly it does not work here. Swift uses the „convention(c)“ syntax to define a pointer to a function of a specific signature. ConnexionMessageHandlerProc becomes

typealias ConnexionMessageHandlerProc = (UInt32, UInt32, UnsafeMutablePointer<Void>) -> Void

which seems to be a legit type alias to use. However, you cannot use it as type for a raw Swift function, simply because Swift functions / methods are solely identifiable (aka typed) by their signature. But a function of an equivalent signature as ConnexionMessageHandlerProc is not identical to this „type“. Xcode tells you that your function with the above stated signature cannot be passed to the SetConnexionHandlers function, because you need a C function pointer and you can only form it by a reference from a ‚func‘. So following this hint you have to do something like

let myFuncReference = myMessageHandlerFuncImpl //without the Signature. It is already provided where you have defined your function

But this will not work, because your message handler function is not of the same type. Interestingly Xcode will, if you try this approach, move the same error message to the SetConnexionHandlers call.

The next idea would be to cast the function to the ConnexionMessageHandlerProc type. Because functions are also first-class citizens you would expect that it could be somehow possible. But its not, simply because Swift does not recognize the Signatures as equivalent. So you cannot cast your function’s reference to the needed type.

This is not the whole truth. There is a way to cast a function to a specific type in Swift: Closures.
Closures are simply anonymous functions, i.e. functions without an identifier name, but with an implementation body. Not having a name doesn’t mean that it does not exist in memory, so you have the function somewhere located at your heap. To access it you need what? Exactly, you need a pointer. And here is Swift’s inconsistency regarding pointers, because you can assign a Closure-definition to an identifier aka variable that can be casted, because it is a type unsafe pointer, fully compatible with C. That took me long to figure out.

Here is what you have to use, fill with life and toss to SetConnexionHandlers

let messageHandler : ConnexionMessageHandlerProc = { (deviceId: UInt32, msgType: UInt32, var msgArgPtr: UnsafeMutablePointer<Void>) -> Void in

// Here goes your data handling
// See next main section

}

let addedHandler : ConnexionAddedHandlerProc = {(deviceId : UInt32) -> Void in

// Here goes your data handling
// See next main section

}

let removedHandler : ConnexionRemovedHandlerProc = {(deviceId : UInt32) -> Void in

// Here goes your data handling
// See next main section

}

As you can see, I used deviceId instead of productId, because I found it more intuitive. Actually, productId seems to be technically more appropriate, because this variable identifies a product type (SpaceMouse Pro, SpaceNavigator, etc.) and not your specific device.
So if you have e.g. two SpaceNavigators connected simultaneously, you will get the same Id regardless of which particular device is active (to distinguish them, you have to use the USB address).

Sadly 3Dconnexion is also not consequent at this point, because inside the ConnexionDevicePrefs structure they also use deviceID (with a capital D) and describe its meaning analogous inside the comments:

uint16_t    deviceID; // device ID (SpaceNavigator, SpaceNavigatorNB, SpaceExplorer...)

I think this was even the reason why I begun to use deviceId in the first place. Whatever…

… the main point is, that it causes no problems in regards of casting the closure.

The fourth parameter defines if you want to handle the incoming data inside a thread different from your main UI thread. This should be considered in a more rendering intensive application, but set this parameter to false for now. I haven’t worked with multithreading inside Swift, yet.

Register your Application aka Client

Next you have to register your application to the driver, so whenever it is in focus it will receive data from the previously provided callback function. Here is the C function responsible for this

uint16_t RegisterConnexionClient(uint32_t signature, uint8_t *name, uint16_t mode, uint32_t mask);

func RegisterConnexionClient(signature: UInt32, _ name: UnsafeMutablePointer<UInt8>, _ mode: UInt16, _ mask: UInt32) -> UInt16

RegisterConnexionClient needs four parameters. The first and second are redundant, so it is up to you which one you want to use. I recommend to use the first one called signature, which is a UInt32 value generated from a four character string that you have to provide at your project setting.

This string is located in the Custom OS X Application TargetProperties pane at the Bundle creator OS Type code field. If you are an OS X developer you will also know this field as the CFBundleSignature value (you can display it as such by right-clicking into the pane and selecting Show Raw Keys/Values). Type in any four character string that serves best as abbreviation for your application name.

To retrieve the value of this field you have to call

let appSignature = NSBundle.mainBundle().objectForInfoDictionaryKey("CFBundleSignature") as? String

You can embed this into an if statement to ensure that appSignature is not nil when you pass it to RegisterConnexionClient, like this

if let appSignature = NSBundle.mainBundle().objectForInfoDictionaryKey("CFBundleSignature") as? String{
    clientId = RegisterConnexionClient(ConnexionClientHelper.Instance.GetUInt32ValueFrom(String: appSignature), nil, ConnexionClient.ClientMode.TakeOver, ConnexionClient.Mask.All)
}else{
    // Handle error
}

You can see two things here:

1. appSignature is a String but an UInt32 is expected
2. I use a static helper function I wrote to convert the four character string into an UInt32.

// Convert a Swift String into a UInt32 C like four-characters encoding used e.g. inside the RegisterConnexionClient() function
func GetUInt32ValueFrom(String string : String) -> UInt32 {
    var result : UInt32 = 0
    if let data = string.dataUsingEncoding(NSMacOSRomanStringEncoding) {
        let bytes = UnsafePointer<UInt8>(data.bytes)
        for i in 0 ..< data.length {
            result = result << 8 + UInt32(bytes[i])
        }
    }
    return result
}

As mentioned in Fiddling With C And Swift, a four character string is common in C, but not directly useable in Swift. So use this function to save yourself a lot of time. What this function does is basically to encode every Unicode character (Swift uses UTF8 encoding by default) to ASCII, using its representing UInt8 value, adding it to a UInt32 variable, and pushing it 8 bits up to make space for the next UInt8 bit-sequence.

The other, redundant way to identify your application would be by providing the application’s full name. Inside C this would be very easy, except figuring out what the „full name“ actually is, in order to pass a String to the function. A C-String is basically just a pointer to the first char inside a sequence in memory, and every following char is just an eight bit offset addition to the predecessor character. In Swift this is not the case and leads to many new questions that I don’t want to discuss here. Just use the previous approach and you’re good to go.

The third parameter is the method of how your application will interact with the driver and the device. You can chose from the two options (note that I am using my swifty ConnexionClient.swift file)

ConnexionClient.ClientMode.TakeOver

and

ConnexionClient.ClientMode.Plugin

TakeOver will let you decide how to configure and use the device. Everything you want from your device, such as calibration and precision you have to set inside your application. Plugin on the other hand uses the driver’s preference that you can set inside the global OS X configuration panel.

Sadly both options currently cause some problems.

• TakeOver sends data to the application, but seams to ignore most of the configuration commands. That’s why my example application is so limited at the moment.
• Plugin does not send axis or button data at all – or at least I haven’t figured out how and where to grab the data (thanks to the very limited documentation – it’s more likely to find a needle inside a haystack).

So I stick with the TakeOver variant for now, because this way usable data will be sent from the device.

The last parameter requires a bit mask that you can find under ConnexionClient.Mask. You can concat different masks by using bitwise OR ( pipe character | ). For now, you can stick with ConnexionClient.Mask.All, which activates broadcasting of every event.

As return value of the RegisterConnexionClient function, you get a unique client ID if everything went fine. Save this Id, because you need it during the whole lifespan of your device interaction.

Here is the resulting code snipped in Swift. Please note that I encapsulated the whole process inside a function called start that is located inside a helper class. This class uses a singleton pattern that I often use while developing in Java for Android and it seams to work very good in Swift, too. Have a look at my entire code on GitHub if you want to see how it’s done.
I also use the weak linking of the framework, as discussed in Weak-linking the framework (C workaround), at this point right before I call the first framework’s function, in order to to avoid a runtime-crash.

func start(MsgHandlerClosure msgHandler : ConnexionMessageHandlerProc, AddedHandlerClosure addHandler : ConnexionAddedHandlerProc, RemovedHandlerClosure remHandler : ConnexionRemovedHandlerProc ) -> Void{
    // Check if 3Dconnexion driver is present or else throw exception
    guard isConnexionDriverAvailable() == true else { // Handle exception }

    // Avoid multiple starts
    guard clientId == 0 else { // Handle exception }
    let error = SetConnexionHandlers(msgHandler, addHandler, remHandler, false)

    guard error == 0 else { // Handle exception }
    
    if let appSignature = NSBundle.mainBundle().objectForInfoDictionaryKey("CFBundleSignature") as? String{
        clientId = RegisterConnexionClient(ConnexionClientHelper.Instance.GetUInt32ValueFrom(String: appSignature), nil, ConnexionClient.ClientMode.TakeOver, ConnexionClient.Mask.All)

        guard clientId != 0 else { // Handle exception }

        SetConnexionClientButtonMask(clientId, (UInt32)(ConnexionClient.Mask.AllButtons));
        SetConnexionClientMask(clientId, ConnexionClient.Mask.All)
    }else{
        // Handle exception
    }
}

The actual start function uses exception handling via throw. I left this out of this example – for simplicity.

There are two more lines of interest

SetConnexionClientButtonMask(clientId, (UInt32)(ConnexionClient.Mask.AllButtons));
SetConnexionClientMask(clientId, ConnexionClient.Mask.All)

This is the first time you configure your device. In this particular case we say that we want to receive events from all buttons pressed and from all axes. The clientId is necessary, to tell the driver who is requesting this behavior. If you have several applications running simultaneously, using this framework, every application can have a different setting configured.

Maybe you ask yourself why I am casting ConnexionClient.Mask.AllButtons to UInt32. This is because 3Dconnexion has implemented this field a an uint64_t type, but their function asks for a 32bit unsigned integer. Basically the value of ConnexionClient.Mask.AllButtons  is zero, but its representation is 0xFFFFFFFF. I have no clue what they where thinking here. Every other button mask is also 64bit. Weird!

Stop driver and perform cleanup

Before digging into data-usage, I show you how to properly shutdown the driver, in order to avoid any memory leakage or unforeseen consequences.

It is a simple process. Just call the following functions in the given order:

UnregisterConnexionClient(clientId)
CleanupConnexionHandlers()

Data usage

During the client registration process, three callback functions were defined in the form of named closures and passed to SetConnexionHandlers. Whenever your device has something to tell to your application, it will be done by one of those callbacks. We already have everything set to use the data passed to the callbacks and only need to implement the data handling.

Message Handler Callback

This closure implements the ConnexionMessageHandlerProc type and handles every event produced by the device’s buttons and axes. So this is where your application gets its interaction data.

Here you see a code skeleton that classifies every event. Making sure that it is a DeviceState message, the msgArgPtr pointer can be safely casted to the ConnexionDeviceState struct and its data can be made available via the memory property of the UnsafeMutablePointer container class.

Furthermore, PrefsChanged and CalibrationDevice messages are intercepted. I haven’t done much with this message types, yet. Perhaps I will write another short tutorial on how to use them, after testing them productively for some use-cases.

let messageHandler : ConnexionMessageHandlerProc = { (deviceId: UInt32, msgType: UInt32, var msgArgPtr: UnsafeMutablePointer<Void>) -> Void in
    // Check the type of the message
    switch(msgType){
    // Every axis or button event is handled here
    case ConnexionClient.Msg.DeviceState:
        // Retrieve the state by casting the untyped msgArgPtr to ConnexionDeviceState and access its content in memory
        let state = (UnsafeMutablePointer<ConnexionDeviceState>(msgArgPtr)).memory
        // Check if the device state is meant for this particular client by comparing the clientIds. 
        // CCH.Instance.ClientId is an example of how to structure and access the previously stored clientId that is not at the scope of this closure.
        if state.client == CCH.Instance.ClientId {
            // Check what kind of command arrived
	    switch(state.command){
            // If an axis value was changed
	    case ConnexionClient.Cmd.HandleAxis:
                break
            // If a button was pressed or released
            case ConnexionClient.Cmd.HandleButtons:
                break            // Ignore unknown states
            default:
                break
            }
        }
        break;
    // Every configuration change is handled here
    case ConnexionClient.Msg.PrefsChanged:
        
        break;
    // Every calibration performed is announced here
    case ConnexionClient.Msg.CalibrateDevice:

        break;
    // Ignoring other unknown message types
    default:
        break;
    }
}

Added Handler Callback

The second callback closure is used to identify if a device was connected to your machine. If so, this callback is called and the deviceId (or productId if you prefer 3Dconnexion’s taxonomy) is passed to you. As mentioned before, the deviceId specifies a device type, not an individual device. How to identify a individual device, I will cover in a later short tutorial.

let addedHandler : ConnexionAddedHandlerProc = {(deviceId : UInt32) -> Void in
    // If a device gets connected you receive its device type id that is always the same for this particular product.
    print("Device added with ID \(deviceId)")
}

Removed Handler Callback

The third callback is the counterpart of the added handler callback. It informs you whenever a device was unplugged from the machine.

let removedHandler : ConnexionRemovedHandlerProc = {(deviceId : UInt32) -> Void in
	print("Device removed with ID \(deviceId)")
	
	CCH.Instance.connectedDevicesDictonary[deviceId] = nil
	
	AppInstance.mainVC.printConnectedDevicesFrom(Dictonary: CCH.Instance.connectedDevicesDictonary, sorted: true)
}

ConnexionDeviceState: Get axis and button values

As mentioned in the Fiddling with C and Swift section, it is currently not possible to provide you a clean and native Swift conversion of the C struct. But Swift’s internal mechanism is smart enough to give you a Swift way of accessing the properties. So if you want to access, for example, the device‘ address and you use state, as shown in the Message Handler Callback section, you do it with the dot-operator, like

state.address

that will give you the USB address at which your device is registered. You saw another example of this in the code skeleton for the Message Handler Callback, where I accessed the command property to distinguish between axis and button events.

Most interesting at this point is how to handle the axis array (I will leave out the report array here, because it provides very unintuitive data, that I don’t understand by that time).

[spoiler title=“Arrays in C“]Arrays in C are just sequentially ordered memory sections of the same type, thus, of the same bit-length. The sum of all sections is the length of the whole array. An array is accessed by a pointer that points at the first bit of the first section of the array and the type of the array tells how many bits to read to get the value of one section. To access every other section you simply add the sections position times the type-length to the pointer’s starting position.[/spoiler]

The C array is automatically converted to a Swift tuple. Therefore, no advance operations of the Swift array implementation can be used. Nevertheless, tuples are great performance-wise and you can access every element in Swift with the dot-operator and the element’s index. However, you can put it without the index directly into a print command to have it pretty printed to the terminal.

Axis tuple

Here is the meaning of the axis array elements.

state.axis.0 // Cap translation in X direction
state.axis.1 // Cap translation in Y direction
state.axis.2 // Cap translation in Z direction
state.axis.3 // Cap rotation around the X axis
state.axis.4 // Cap rotation around the Y axis
state.axis.5 // Cap rotation around the Z axis

Button bit-mask

Every button on your device is associated with an Id. However, an Id doesn’t come in its own variable or inside an array element.

The documentation on this made me wonder for a moment

Reports which buttons, if any, are pressed. Buttons are assigned 2n values, i.e. 1, 2, 4, 8, 16, and so on. The buttons field is a sum of all the values being pressed. For example, if button 1 and button 2 are both pressed, the buttons field will be 3. When all buttons are released, the buttons field will be 0.

func IsButtonActive(withId id: UInt32, var inside buttons: UInt32) -> Bool{
    buttons = buttons >> (id - 1)
    return (buttons & bitMaskOne) == BitMaskOne
}

for idx in 1...32{
    if(CCH.Instance.isButtonActive(withId: UInt32(idx), inside: state.buttons)){
        // idx holds the ordinal value of the active button Id
    }
}

func getArrayOfButtons(var buttons : UInt32) -> [Bool]{
    var btnDictonary = [Bool](count: 32, repeatedValue: false)
        for bitIdx in 0...31{
            if (buttons & BitMaskOne) == BitMaskOne{
                btnDictonary[bitIdx] = true;
            }
            buttons = buttons >> 1
        }
    return btnDictonary
}