What is the Install API?
Previous Topic  Next Topic 

The Install API is a set of functions that can be used in your installer to create more complex installers than is normally available through the standard actions and conditions.  Some of the actions and conditions in InstallJammer even use pieces of the Install API to do the real work.


The Install API is loaded with procs that you can call from Execute Script actions or Script Condition conditions that give you program-level access to the inner workings of InstallJammer.


Technical Detail

It is important to know that the Install API is built on-the-fly as your installer is packaged.  Only procs that you actually use in your installer will be included in the packaged installer.  This really only means that you cannot make API calls from a running console unless you are already using that API somewhere in your installer since the API call would not have been built into your installer.



Calling an Install API proc

All of the procs in the Install API are in the ::InstallAPI namespace.  To call a proc in the Install API, simply use the fully-qualified name of the proc in your code.  All arguments passed to an Install API proc are non-positional key-value pairs.  That means that it doesn't matter what order you pass the arguments in since each argument is specified as a -option with a value.


For example, let's say we had an Execute Script action where we wanted to do some checking and then set a virtual text variable.  It might look something like this:

if {![::InstallAPI::VirtualTextExists -virtualtext Foo]} {

    ::InstallAPI::SetVirtualText -virtualText Foo -value Bar

}


As you can see from the example, we make two calls to procs in the ::InstallAPI namespace.  This code uses ::InstallAPI::VirtualTextExists to check and see if the virtual text Foo exists, and if it doesn't already exist, we're going to use ::InstallAPI::SetVirtualText to set it to Bar.


The arguments -virtualtext Foo passed to ::InstallAPI::VirtualTextExists tells the call that we want to check if the virtual text variable Foo exists.  The arguments -virtualtext Foo -value Bar tell ::InstallAPI::SetVirtualText that we want to set the virtual text variable Foo to the value Bar.



Finding the arguments to an API call

All API calls are loaded into the install builder when it loads, so you can easily go into the console (through the Help->Show Debug Console menu) and type an Install API call to see what it can do.  To see the usage for an API call, type the name of the call and the argument -? into the console.  Like this:

::InstallAPI::SetVirtualText -?


This will dump the usage information, including all possible arguments, for the ::InstallAPI::SetVirtualText API call.  Of course, you can always read the documentation for each call as well, but this might be quicker for some people.