The IMPORT statement imports a function exported from a DLL. This is primarily intended to allow access to Win32API functions, therefore the exported function must be exported as STDCALL. If you do not understand what this means, it is advisable only to use import with Win32API functions. If you do understand what this means, you may write your own DLLs to interface with your plugin.

You may add as many IMPORT statements as you wish to your plugin source code. The compiler will automatically discard any IMPORT statements that are not referenced in your code (ie: if you import a function but do not use it, the import is not included in your SSE).

There is an extended tutorial on the IMPORT statement and the process available here.

Parameters

dllname

The name of the DLL containing the function to import, EXCLUDING the ".dll" extension. No paths may be specified. The order of search to locate the DLL is as follows:

1. In the <Brass Install Folder>\SSE\<SSENAME> folder
2. The current directory (the Brass installation folder)
3. The system path (includes the Windows folder)
4. In the <Brass Install Folder>\Extensions folder (this folder may not exist, which is fine)
5. In the <Brass Install Folder>\SSE folder
6. In the <Brass Install Folder>\DLL folder (this folder may not exist, which is fine)

Item 1 specifies <SSENAME> as the folder. Brass will look for a folder named the same as the SSE being loaded, excluding the .SSE extension. For example, if the user loads MyPlugin.SSE that references blah99.DLL, Brass will first attempt to load <Brass Install Folder>\SSE\MyPlugin\Blah99.dll. By searching the SSE-specific folder first, it is possible to distribute different versions of an identically named DLL without affecting other plugins.

The tutorial referenced above explains why paths are not allowed.

 

returntype

The type of variable this function returns, declared as a Shiny type.

 

functionname

The name of the function exported from the DLL. This is case sensitive.

 

opt_alias

An optional alias for this function. If you need to import 2 functions with the same name from different DLL's, or if you want to supply an alternative name (for example, "CDA" instead of "CreateDirectoryA") for an imported function, you may supply an alias here. You must use this alias throughout the plugin source code, you may not switch between the original and aliased name. Using an alias is a develop-time enhancement, aliases are resolved to their actual function names during compilation and are discarded before the final compiled SSE is created.

 

parameters

Optional. If the exported function requires parameters, this should be a comma separated list of Shiny types compatible with the function parameters. Each type may optionally be suffixed with:

• "byval" - signifies this parameter should be passed by value. Constants are allowed for this parameter.
• "byref" - signifies this parameter should be passed by reference. Only variables are allowed as their contents will be updated.

If neither BYVAL no BYREF is specified, BYVAL is assumed to be the default type. Refer to STRALLOC for information on BYREF.

 

Return Value

Not applicable.

Example Code

// Import the MessageBoxA function from user32.dll
import user32 int MessageBoxA(int, string, string, int);

// Import the GetCurrentDirectoryA function
import kernel32 int GetCurrentDirectoryA(int, string byref);

// Import the GetCurrentDirectoryA function aliased as GetCurDir
import kernel32 int GetCurrentDirectoryA as GetCurDir(int, string byref);