LimeLM
wyBuild
Support forum
wyDay blog
wyDay Home

Using TurboFloat with Visual Basic 6

Before you can do anything, you need to login to your LimeLM account (or sign up). Then download TurboFloat for Windows on your API page.

Adding floating licensing to your appTurboActivate.dat and Version GUID

After you've created a new product, go to the version page of the product you will be adding licensing to. You will need to do 2 things:

  1. Download the TurboActivate.dat file for the product version.
  2. Make a note of the Version GUID.

You'll be including the TurboActivate.dat file in the same folder as the TurboFloat.dll file and you'll use the Version GUID in your code as part of integrating TurboFloat within your app.

Fix the "Error Trapping" settings in VB6

The first thing you need to do is fix a setting in the Visual Basic 6 IDE. Click the "Tools -> Options..." menu. Then click the "General" tab and set the "Error Trapping" to "Break on Unhandled Errors". Then press OK.

Error trapping - Break on Unhandled Errors

Example project

Included in TurboFloat Library package is a simple VB6 example project. You can find it in the "API\VB6" folder after you've downloaded and extracted the TurboFloat Library package. We recommend playing around with the example app first, before you start integrating TurboFloat into your application.

The following files are what you'll be including in your app:

Use the "stdcall" version of TurboFloat

Visual Basic 6 is a special kind of beast. Instead of using the regular "cdecl" TurboFloat.dlls available in either the "x86" or "x64" folders inside the "Main TurboFloat package", you'll have to use the TurboFloat.dll from inside the "stdcall\x86" folder.

A note about some VB6 bugs

Visual Basic 6 is an ancient language that will seemingly never die. So, until VB6 dies (and you switch to the infinitely better VB.NET), you'll have to make note of, and workaround, the following bugs in Visual Basic 6:

Bug #1: You must always open the project file by double clicking it

You must always open your VB6 project file by double clicking your *.vbp file. You cannot open the project by clicking "File -> Open Project..." or by clicking the filename in the recent projects list in the "File". The reason you absolutely cannot do those things is that VB6 won't be able to load our native "TurboFloat.dll" if you do anything other than open your project by double clicking your project file.

Bug #2: Don't click the "stop" or "end" buttons

Unfortunately the entire VB6 IDE crashes if you don't exit your app normally (by closing your app like you would any other program). If you click the "End" button to stop the debugging then the VB6 IDE crashes.

Bug #3: You can only use ports between 0 and 32,767

VB6 doesn't support "unsigned short" values, meaning you can only use Ports between 0 and 32,767 (anything about 32,767 will cause an overflow).

Bug #4: VBA / VB6 don't support proper threading

Because VBA & VB6 don't support threading there's one feature that won't be available in this language that is available in modern languages. When the "tf_LeaseChange" is called by TurboFloat the "TF_CB_FEATURES_CHANGED" will never be returned for the status. Even if there are new custom license fields delivered by the TurboFloat Server, you'll never be notified that they came in.

Step-by-step walkthrough

We're going to walk you through adding floating licensing to your app by using our VB6 example application. If you haven't downloaded it already you can get the example app inside the TurboFloat Library package.

Step 1. Start the TurboFloat Server

Before you can continue, you need to start a TurboFloat Server instance. We recommend spinning-up a TurboFloat Server instance on our infrastructure using LicenseChest. Alternatively, your customers can host the TurboFloat Server on their own infrastructure by activating and installing the TurboFloat Server locally.

We recommend using our hosted TurboFloat Server option because it's fast, stable, up-to-date, and incredibly easy to deploy.

Step 2. Request "license lease"

In the example "Text Editor" VB6 application the "frmMain.frm" file is the main UI for the app. That is, it's the entry point for the application. And because it's the entry point of the application it's where we'll be requesting the "license lease" from the TurboFloat Server.

First, create the TurboFloat instance in your main form:

' define the TurboFloat instance ("tf") and
' tell it to handle events
Public WithEvents tf As TurboFloat

Then, in the Form_Load event handler for the form, you'll actually create the new instance of the TurboFloat class. Paste the Version GUID you copied from earlier:

Private Sub Form_Load()

    ' create the new TurboFloat instance
    Set tf = New TurboFloat

    ' tell your app to handle errors in the section
    ' at the end of the sub
    On Error GoTo TFProcError

    'TODO: goto the version page at LimeLM and paste this GUID here
    Call tf.Init(Me, "PASTE-VERSION-GUID-HERE")


ProcExit:
    Exit Sub

TFProcError:
    ' err handling code here
End Sub

Next, we'll actually request the lease from the TurboFloat Server:

'TODO: goto the version page at LimeLM and paste this GUID here
Call tf.Init(Me, "PASTE-VERSION-GUID-HERE")

' request the lease
Call tf.RequestLease

Step 3. Handle the "LeaseChange" event

The native TurboFloat library handles all the details about renewing leases, retrying, etc. All you have to do is handle the cases where TurboFloat talks to your app and tells it something has changed (license lease failing to be renewed or new license field data). To do this you need to handle the LeaseChange event:

Private Sub tf_LeaseChange(ByVal status As TF_LeaseStatus)

    If status = TF_CB_FEATURES_CHANGED Then
        'TODO: if you're using feature values in your app
        '      you might want to reload them now.

    Else ' TF_CB_EXPIRED, TF_CB_EXPIRED_INET, and everything else

        ' Immediately disable the app and/or show a modal
        ' form that gives the user the option to Save /
        ' Save As the data (if applicable) and let the
        ' user re-try connecting to the server.
        Me.Enabled = False

        'Note: Don't just close your app. Your users will be
        '      rightfully ticked-off if you do something like that.

        ' Instead, we're showing a modal dialog that lets the
        ' user try to get a new lease from the server. Or,
        ' if they can't, then save their data.

        Dim frmLeaseExp As LeaseExpired
        Set frmLeaseExp = New LeaseExpired

        If frmLeaseExp.ShowDialog(tf) = vbCancel Then
            ' close the app immediately
            Unload Me
            Exit Sub
        End If

        ' We've gotten a new lease, so re-enable the app.
        Me.Enabled = True
    End If
End Sub

Step 4. Finishing touches

Included in the example VB6 app are 3 forms that you might want to copy to your own application:

  1. LeaseExpired.frm: a form to show if the license lease has expired.

    Lease expired

  2. frmInternetErr.frm: a form to show if there's an internet error (that is, a server is specified, but your app couldn't connect to the server).

    Internet error

  3. ServerConfig.frm: a form to allow the end-user to enter details about where their TurboFloat Server is located.

    Config TurboFloat Server location

    This simple dialog gives your customers easy entry of the details needed to connect to their TurboFloat Server instance, whether they host it on our infrastructure using LicenseChest or they host it locally.

You've already seen example usage of the LeaseExpired form in the LeaseChange event handler. Here's an example usage of the ServerConfig and frmInternetErr forms. Its logic is fairly simple. First it tries to get a lease, and if that fails then it prompts the user for action:

Private Sub Form_Load()

    ' create the new TurboFloat instance
    Set tf = New TurboFloat

    ' tell your app to handle errors in the section
    ' at the end of the sub
    On Error GoTo TFProcError

    'TODO: goto the version page at LimeLM and paste this GUID here
    Call tf.Init(Me, "18324776654b3946fc44a5f3.49025204")

    ' request the lease
    Call tf.RequestLease


AfterRequest:
    ' If you've reached this point then your app has
    ' successfully acquired a license lease. If you
    ' have custom license field values that you want
    ' to use, you can get them now.
    ' See: https://wyday.com/limelm/help/license-features/

    'Dim fieldValue As String
    'fieldValue = tf.GetFeatureValue("your field name", "default value")
    'TODO: do something with the fieldValue

ProcExit:
    Exit Sub

TFProcError:

    If Err.Number = TF_E_INET Or _
       Err.Number = TF_E_INET_TIMEOUT Or _
       Err.Number = TF_E_WRONG_SERVER_PRODUCT Or _
       Err.Number = TF_E_SERVER_UUID_MISMATCH Or _
       Err.Number = TF_E_USERNAME_NOT_ALLOWED Then

        ' Give the user an option to try another server if they
        ' couldn't connect to the first one, or if the first one
        ' is for a different product.
        Dim inetErr As frmInternetErr
        Set inetErr = New frmInternetErr

        If inetErr.ShowDialog(tf) = vbOK Then
            Resume AfterRequest
        Else
            ' close the app immediately
            Unload Me
            Exit Sub
        End If

    ElseIf Err.Number = TF_E_SERVER Then

        ' if it's a server error, then prompt for the server
        Dim srvConf As ServerConfig
        Set srvConf = New ServerConfig

        If srvConf.ShowDialog(tf) = vbOK Then
            Resume AfterRequest
        Else
            ' close the app immediately
            Unload Me
            Exit Sub
        End If
    End If


    MsgBox "Failed to get a lease from the floating license server: " & Err.Description

    ' End your application immediately
    Unload Me
End Sub

Step 5. Dropping the lease when your app closes

After you've successfully requested a lease from the TurboFloat Server, the TurboFloat library integrated in your app takes care of renewing the leases automatically and silently. You'll only ever get a notification of something going wrong in the handler for the LeaseChange event that we covered in Step 3.

When your app is closing you should "drop" the lease using the DropLease() method, and cleanup the memory using the Cleanup() method:

Private Sub Form_Unload(Cancel As Integer)
    ' since we're closing we can just skip the errors if the dropped
    ' lease fails the lease will become a zombie.
    On Error Resume Next

    ' drop the lease
    If tf.HasLease Then
        Call tf.DropLease
    End If

    ' cleanup memory, etc.
    ' Note: if you're going to wait for a successful "DropLease" call
    '       (instead of the current behavior of trying to drop the
    '       lease and exiting whether the lease was dropped or not)
    '       then you must not call tf.Cleanup until you finished
    '       calling any other TurboFloat function. I.e. only call
    '       tf.Cleanup as the last TurboFloat function.
    Call tf.Cleanup
End Sub

What this does is tell the TurboFloat Server that you're through using the lease in this instance of your app, and another instance of your app on another computer or another session can now use that "free slot".

If you can't drop the lease (because your app can't connect to the internet, or for any other reason), and you choose to exit your app anyway, then the "lease" on the TurboFloat Server will be a "zombie". The lease will expire eventually on the TurboFloat Server, and thus the free slot will open back up.

Step 6: Testing the lease change event

Testing requesting leases, dropping them, and everything else in the TurboFloat Library is intuitive: just call the function and it does the thing you want it to do. Testing the lease change event is, however, slightly less intuitive. Here's how you can test the lease change event:

  1. If your app is open and has a lease, close your app and make sure it drops the license lease from the TurboFloat Server.

  2. Stop the TurboFloat Server instance.

  3. Open the TurboFloat Server config file, and edit <lease .../> element and set it to "30". This will set the lease length to 30 seconds.

  4. Save the changes you made to the configuration file.

  5. Start your TurboFloat Server instance again.

  6. Start your app again, and make sure it successfully gets a license lease from the TurboFloat Server.

  7. Now, stop the TurboFloat Server instance, but leave your app running.

  8. Within the next 30 seconds the lease change event will be called because the TurboFloat Library was not able to renew the license lease automatically.

About  ·  Careers  ·  Contact us  ·  Privacy  ·  Site Map
© 2023 wyDay