Operation Description¶
Calling DLL Functions¶
Operation¶
FCALL_LoadLibrary [ /Z[=z] ] /PATH=path libName, handle
Description¶
Loads an external library and returns its handle.
Flags¶
Flags |
Description |
|---|---|
/Z=z |
z is a number and can be 0 or 1.
|
/PATH=path |
path is an Igor path variable. Sets path where library with libName is located. |
Parameters¶
Parameters |
Description |
|---|---|
libName |
Name of library file as string. |
handle |
string variable that returns the handle information. The handle identifies uniquely a loaded library and is used as is with FCALL_FreeLibrary and FCALL_CallFunction. |
Returns¶
V_flag: Contains the error code when flag /Z=1 is set. V_flag is not changed otherwise.
Errors¶
The following list contains only XOP specific errors.
Error code |
Description |
|---|---|
variable given as handle is not a string. |
|
Loading the external library failed.
The error code retrieved from the system call
|
Operation¶
FCALL_FreeLibrary [ /Z[=z] ] handle
Description¶
Unloads a previously loaded external library.
Flags¶
Flags |
Description |
|---|---|
/Z=z |
z is a number and can be 0 or 1.
|
Parameters¶
Parameters |
Description |
|---|---|
handle |
string containing the handle information. The handle is retrieved with FCALL_LoadLibrary. |
Returns¶
V_flag: Contains the error code when flag /Z=1 is set. V_flag is not changed otherwise.
Errors¶
The following list contains only XOP specific errors.
Error code |
Description |
|---|---|
Content of handle string could not be converted to UINT64. |
|
|
Operation¶
FCALL_CallFunction [ /Z[=z] ] handle, functionName, parameterIn, parameterOut
Description¶
Calls function functionName in previously loaded library identified by handle.
Flags¶
Flags |
Description |
|---|---|
/Z=z |
z is a number and can be 0 or 1.
|
Parameters¶
Parameters |
Description |
|---|---|
handle |
string containing the handle information. The handle is retrieved with FCALL_LoadLibrary. |
functionName |
string with the function name as defined in the library. |
parameterIn |
string in JSON format that defines the functions parameters. See chapter Parameter Definition for detailed discussion. |
parameterOut |
string variable in JSON format that returns data from the function called. See chapter Parameter Definition for detailed discussion. |
Returns¶
V_flag: Contains the error code when flag /Z=1 is set. V_flag is not changed otherwise.
Errors¶
The following list contains only XOP specific errors.
Error code |
Description |
|---|---|
variable given as parameterOut is not a string. |
|
|
|
|
|
The XOP encountered an internal assertion. This usually indicates a bug in the XOP. |
|
A string input could not be converted to a requested number type. |
|
An input wave has an incorrect type. |
Retrieving Function Information¶
Operation¶
FCALL_GetFunctionList [ /Z[=z] ] /PATH=path fileName, functionList
Description¶
Parses a C header (*.h) file and returns all declared functions in a semicolon separated list.
Flags¶
Flags |
Description |
|---|---|
/Z=z |
z is a number and can be 0 or 1.
|
/PATH=path |
path is an Igor path variable. Sets path where header file with function declaration is located. |
Parameters¶
Parameters |
Description |
|---|---|
fileName |
Name of C header file as string. |
functionList |
string variable that returns the semicolon separated list of declared functions. |
Returns¶
V_flag: Contains the error code when flag /Z=1 is set. V_flag is not changed otherwise.
Errors¶
The following list contains only XOP specific errors.
Error code |
Description |
|---|---|
variable given as functionList is not a string. |
|
The header file can not be indexed. This error usually indicates that that the indexer can not create a translation unit context. |
|
The header file can not be parsed. This error usually indicates a problem with the format of the header file. |
Operation¶
FCALL_GetParamTypeList [ /Z[=z] ] /PATH=path fileName, functionName, paramTypeList
Description¶
Parses a C header (*.h) file and returns the types of all parameters of a declared function in a semicolon separated list.
Flags¶
Flags |
Description |
|---|---|
/Z=z |
z is a number and can be 0 or 1.
|
/PATH=path |
path is an Igor path variable. Sets path where header file with function declaration is located. |
Parameters¶
Parameters |
Description |
|---|---|
fileName |
Name of C header file as string. |
functionName |
string with the name of a function declared in the specified file. |
paramTypeList |
string variable that returns the semicolon separated list of the types of the specified functions parameters. See Details. |
Returns¶
V_flag: Contains the error code when flag /Z=1 is set. V_flag is not changed otherwise.
Errors¶
The following list contains only XOP specific errors.
Error code |
Description |
|---|---|
variable given as paramTypeList is not a string. |
|
The header file can not be indexed. This error usually indicates that that the indexer can not create a translation unit context. |
|
The header file can not be parsed. This error usually indicates a problem with the format of the header file. |
Details¶
The elements returned in paramTypeList consist of pairs in the form type,size. The order of the pairs in the list represents the parameter order of the function declaration starting with the return type as first entry.
The following table lists the available types and their corresponding sizes in bytes.
Type |
Size |
Description |
|---|---|---|
VOID |
0 |
none |
UINT8 |
1 |
Unsigned 8 bit integer |
UINT16 |
2 |
Unsigned 16 bit integer |
UINT32 |
4 |
Unsigned 32 bit integer |
UINT64 |
8 |
Unsigned 64 bit integer |
INT8 |
1 |
Signed 8 bit integer |
INT16 |
2 |
Signed 16 bit integer |
INT32 |
4 |
Signed 32 bit integer |
INT64 |
8 |
Signed 64 bit integer |
FLOAT |
4 |
Single Precision floating point number |
DOUBLE |
8 |
Double Precision floating point number |
PTR:pointer-type |
8 |
The type of the pointer follows recursively after the colon. It can be any of the types listed in this table. |
PTR:RECORD |
8 |
The parameter is a pointer to a structure. |
UNSUPPORTED |
x |
Unsupported type. Size is returned by the parser. |
Note for the special case PTR:pointer-type: The size returned in such paramTypeList entry is not the size of PTR which is always 8. Instead the size of the element the last resolved pointer points to is returned.
Example for a PTR: A C declaration of int* is returned as type PTR:INT32,4.
The size of the pointer itself is always 8, the typed pointer points to an 32-bit integer that has a size of 4 bytes. This allows a user to prepare a memory buffer with correctly typed elements for returned data.
Example for a simple type: A C declaration of int is returned as list entry INT32,4.
Example for a PTR with recursive resolution: A C declaration of void** is returned as PTR:PTR:VOID,0.
Examples:
Declaration |
paramTypeList |
|---|---|
void fun() |
VOID,0 |
int fun(char c, float f) |
INT32,4;INT8,1;FLOAT,4 |
void fun(short** v, myStruct s, someObject o) |
VOID,0;PTR:PTR:INT16,2;PTR:RECORD,8;UNSUPPORTED,8 |
