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.

/Z=1
Suppresses runtime error generation if operation fails. Error code is returned in V_flag.
/Z=0
Enables generation of runtime error if operation fails.
/Z
same as /Z=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
FCALL_ERROR_REF_VAR_DIFF_TYPE variable given as handle is not a string.
FCALL_ERROR_LOADLIBRARY_FAILED Loading the external library failed. The error code retrieved from the system call LoadLibrary is written with the error message to the Igor console. For system error codes see SYSTEM_ERROR_CODES.

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.

/Z=1
Suppresses runtime error generation if operation fails. Error code is returned in V_flag.
/Z=0
Enables generation of runtime error if operation fails.
/Z
same as /Z=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
FCALL_ERROR_LIBHANDLE_FAILED Content of handle string could not be converted to UINT64.
FCALL_ERROR_FREELIBRARY_FAILED
One of the following errors:
  • handle string is empty.
  • converted handle is null.
  • Freeing the external library failed The error code retrieved from the system call FreeLibrary is written with the error message to the Igor console. For system error codes see SYSTEM_ERROR_CODES.

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.

/Z=1
Suppresses runtime error generation if operation fails. Error code is returned in V_flag.
/Z=0
Enables generation of runtime error if operation fails.
/Z
same as /Z=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
FCALL_ERROR_REF_VAR_DIFF_TYPE variable given as parameterOut is not a string.
FCALL_ERROR_LIBHANDLE_FAILED
One of the following errors:
  • handle string is empty.
  • handle string could not be converted to UINT64
  • converted handle is null.
FCALL_ERROR_GETPROCA_FAILED
One of the following errors:
  • functionName string is empty.
  • Retrieving function from the library failed. The error code retrieved from the system call GetProcAddress is written with the error message to the Igor console. For system error codes see SYSTEM_ERROR_CODES.
FCALL_ERROR_ERR_ASSERT The XOP encountered an internal assertion. This usually indicates a bug in the XOP.
FCALL_ERROR_ERR_CONVERT A string input could not be converted to a requested number type.
FCALL_ERROR_ERR_INVALID_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.

/Z=1
Suppresses runtime error generation if operation fails. Error code is returned in V_flag.
/Z=0
Enables generation of runtime error if operation fails.
/Z
same as /Z=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
FCALL_ERROR_REF_VAR_DIFF_TYPE variable given as functionList is not a string.
FCALL_ERROR_GETCINDEX_FAILED The header file can not be indexed. This error usually indicates that that the indexer can not create a translation unit context.
FCALL_ERROR_PARSE_FAILED 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.

/Z=1
Suppresses runtime error generation if operation fails. Error code is returned in V_flag.
/Z=0
Enables generation of runtime error if operation fails.
/Z
same as /Z=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
FCALL_ERROR_REF_VAR_DIFF_TYPE variable given as paramTypeList is not a string.
FCALL_ERROR_GETCINDEX_FAILED The header file can not be indexed. This error usually indicates that that the indexer can not create a translation unit context.
FCALL_ERROR_PARSE_FAILED 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