Dll

Description

availability: SWFKit Pro 2.0

Calling dynamic-link libraries (.dll files) in FFish Scripting language. With the Dll object, you can call functions developed by C/C++, Pascal, Basic, etc to extend the power of Flash.

SWFKit Pro 3 supports two methods of importing an external function in a dll. The first one is to call the registerFunction method of the Dll object, and the second one is to use the dllimport keyword. The latter method is recommended. You can read the manual page of the registerFunction method to learn how to use it. At here we will only introduce the dllimport keyword as follows.

The dllimport keyword is used to import an external function so that you can call the function in ffish script as if it is a built-in function. The dllimport clause has the form

dllimport libraryName callType returnType functionName(arg0, arg1, ..., argN) [as alias];

Where libraryName is the path name of the dll that contains the function to import. It can be either a string constant or a string variable. callType specifies the calling convention of the function to import, which can be either stdcall or cdecl. The fastcall calling convention is not supported in SWFKit Pro 3.0 yet. returnType specifies the return type of the function. functionName is the name of the function exported by the dll. arg0, arg1, ... argN declare the parameters of the function, which define the type of the each parameter, with or without the name of each parameter. alias is optional, which specifies the alias of the function. If you specify an alias for the function, you must call the function by using the alias in ffish script; otherwise, you must use the functionName to call it. For instance:

dllimport "user32.dll" stdcall long GetWindowLong(pointer, int) as
user32_getWindowLong;

var GWL_STYLE = -16;
var styles = user32_getWindowLong(getMainWnd().handle, GWL_STYLE);
trace(styles);

SWFKit supports the following types of the return values and parameters:

void

For returns only, you cannot declare a parameter to be of this type. This type means that the function has no return.

char

The return value or a parameter is a character. When a function returns a value of char type, the value will be converted to a Number object in ffish script that contains the ASCII value of the character. String objects and Number objects can be passed as a parameter of char type. Only the first character of a String object will be used to set the value of the parameter; if a Number object is used, SWFKit will convert its value to a character and then pass the character to the function.

unsigned char

The return value or a parameter is an unsigned character. This type is similar to the char type.

char*

The return value or a parameter is a pointer to a char value or a ansi string. When a function's return is of char* type, SWFKit will simply convert it to a Number object that represents the address of the pointer, not the value it points to. In fact SWFKit will always do in this way when a function returns a pointer. The address of the pointer should be retained because the pointer may point to an allocated memory and may be used to free the memory later. You can use the getPointerXXXValue methods of the Dll object such as getPointerStringValue, getPointerWideStringValue, etc to get the value it points to. When a parameter is of char* type, you can use A String object or A Number object to pass parameter. SWFKit will convert a String object to a c-style string (a null terminated string) before pass it to the function if the parameter is of char* type. For a Number object, SWFKit will first convert it to a char value and then allocate a pointer to pass to the function, which points to the converted char value.

unsigned char*

Similar to the char* type.

short

The return value or a parameter is a short integer (A short integer is 16 bits). When a function returns a value of short type, the value will be converted to a Number object. String objects and Number objects can be passed as a parameter of short type. Only the first character of a String object will be used to set the value of the parameter; if a Number object is used, SWFKit will convert it to a short integer and then pass the value to the function.

unsigned short

Similar to the short type.

short*

The return value or a parameter is a pointer to a short integer or a wide string. When a function returns a value of short* type, SWFKit will simply convert it to a Number object that represents the address of the pointer. When a function's parameter is of short* type, you can use a String object or a Number object to pass parameter. SWFKit will convert a String object to a wide string (null terminated) before pass it to the function. For a Number object, SWFKit will first convert it to a short integer and then allocate a pointer to pass to the function, which points to the converted short integer.

unsigned short*

Similar to the short* type.

long

The return value or a parameter is a 32-bit long value. When a function returns a value of this type, the value will be converted to a Number object. String objects, Number objects and Boolean objects can be passed as parameters of long type. Only the first character of a String object will be used to set the value of the parameter; if a Number object or a Boolean object is used, SWFKit will convert it to a long value and then pass the value to the function.

unsigned long

Similar to the long type.

long*

The return value or a parameter is a pointer to a long value. When a function returns a value of long* type, SWFKit will simply convert it to a Number object that represents the address of the pointer. When a function's parameter is of long* type, you would have to use a Number object or a Boolean object to pass value to it. In this case, SWFKit will convert the Number object or the Boolean object to a long value, and then allocate a pointer to pass to the function, which points to the converted long value.

unsigned long*

Similar to the long* type.

int

Same as the long type.

unsigned int

Same as the unsigned long type.

int*

Same as the long* type.

unsigned int*

Same as the unsigned long* type.

int64

The return value or a parameter is a 64-bit long integer. When a function returns a value of this type, the value will be converted to a Number object. String objects and Number objects can be passed as parameters of int64 type. Only the first character of a String object will be used to set the value of the parameter; if a Number object is used, SWFKit will convert it to a 64-bit long integer value and then pass the value to the function.

int64*

The return value or a parameter is a pointer to a 64-bit signed integer. When a function returns a value of int64* type, SWFKit will simply convert it to a Number object that represents the address of the pointer. When a function's parameter is of int64* type, you would have to use a Number object to pass value to it. In this case, SWFKit will convert the Number object to a 64-bit long integer, and then allocate a pointer to pass to the function, which points to the converted 64-bit integer.

unsigned int64

Similar to the int64 type.

unsigned int64*

Similar to the int64* type.

float

The return value or a parameter is a 4-byte floating-point number. When a function returns a value of this type, the value will be converted to a Number object. String objects and Number objects can be passed as parameters of this type. Only the first character of a String object will be used to set the value of the parameter; if a Number object is used, SWFKit will convert it to a floating-point number and then pass the value to the function.

double

Similar to the float type. The difference between the float type and the double type is that the double type is 8 bytes long.

float*

The return value or a parameter is a pointer to a 4-byte floating-point number. When a function returns a value of float* type, SWFKit will simply convert it to a Number object that represents the value of the pointer. When a function's parameter is of float* type, you would have to use a Number object to pass value to it. In this case, SWFKit will convert the Number object to a 4-byte floating-point number, and then allocate a pointer to pass to the function, which points to the converted 4-byte floating-point number.

double*

Similar to the double type.

pointer

The return value or a parameter is a pointer to an unspecified type. When a function returns a value of pointer type, SWFKit will simply convert it to a Number object that represents the address of the pointer. Similarly, you can pass a Number object as a parameter of pointer type to a function. In this case, SWFKit does not allocate a pointer to pass to the function. Instead, the value of the Number object is converted to a pointer and passed to the function, that is, the Number object must represent address of a pointer.

A Struct object or a StringStream object can also be used to pass as a pointer type parameter. In this case, SWFKit will allocate a pointer to pass to the function, which points to the binary data hold by the Struct object or the StringStream object.

String

Same as the char* type.

Boolean

Same as the long type.

Boolean*

Same as the long* type.

StructName

The "StructName" must be a pre-declared structure type. The details of structure type will be introduced later in this manual page. If the return value of a function is of structure type, SWFKit will convert the return value to a Struct object. If a parameter of a function is of structure type, you can use a Struct object or a StringStream object that has the same data size as that of the pre-declared structure type to pass value to the function.

StructName*

The return value or a parameter is a pointer to a pre-declared structure type "StructName". If the return value of a function is of this type, SWFKit will simply convert it to a Number object that represents the address of the pointer. If a parameter of a function is of this type, you can use a Struct object or a StringStream object to pass value to the function. In this case, a pointer is allocated and passed to the function, which points to the binary data hold by the Struct object or the StringStream object.

Note: the above types can only be used to declare dll functions in FFish Script. You cannot use them to declare a FFish Script variable. Pointer to pointer type is also not supported, e.g. char ** is not supported, you would have to use the pointer type instead.

The structure type For convenience of calling dll functions in FFish Script, we introduces a new element into the FFish Scripting language - the structure type. A structure type is declared by the struct keyword, and the declaration of a structure type is similar to that in the c/c++ languages. The declaration of a structure type has the following form:

struct
{
    type0 itemName0;
    type1 itemName1;
    ...
    typeN itemNameN;
} StructName;

where typeN is the type of the Nth member of the structure. itemNameN is the name of the Nth member. StructName is the name of the structure type. The valid types of a structure member are the same as those of a function parameter. Moreover, SWFKit Pro 3 supports embedded structure members and array members. E.g.

struct
{
    int value[4];
} myStruct;

struct
{
    myStruct myItem;
    struct
    {
        int iValue;
        float fValue;
    } myEmbeddedStructItem;
} myStruct2;

The struct keyword only declares a structure type. To create an instance of the declared structure type, you should create a Struct object by using the new operator. E.g.

var struct1 = new Struct(myStruct);
var struct2 = new Struct(myStruct2);

struct1.value[0] = 0;
struct2.myEmbeddedStructItem.iValue = 100;

Pass values to parameters by referenceGenerally, SWFKit Pro pass parameters to functions by value. However, many dll functions have out parameters, that is, these parameters will be used for output so that they must be passed by reference. The ffish scripting language does not support to pass parameters by reference directly, so an alternative calling method is introduced into the ffish scripting language to support this feature. The method is to use Object objects to pass parameters to functions. The objects used to do this must have a "value" property, which is the actual variable to pass to the functions. After calling the functions, the "value" property of the objects will contain the new value output by the functions.