Multi API-DLL Functions

These functions operate on meta-data within the Multi API-DLL and help manage the underlying API-DLL instances. These functions do not directly program target devices. Use these functions to initialize the desired number of FPAs, selected all or one FPA(s), read FPA serial numbers, or clean-up resources used by Elprotronic’s DLLs.

Once the desired FPAs have been successfully opened, use Generic Functions to initialize the FPAs, and configure them for the target device(s) being programmed.

1 1. F_OpenInstancesAndFPAs
2 2. F_CloseInstances
3 3. F_Set_FPA_index
4 4. F_Get_FPA_index
5 5. F_Check_FPA_index
6 6. F_Enable_FPA_index
7 7. F_Disable_FPA_index
8 8. F_LastStatus
9 9. F_Multi_DLLTypeVer
10 10. F_Get_FPA_SN
11 11. F_Get_FPA_Label
12 12. F_Get_FPA_List
13 13. F_GetProgressBar
14 14. F_GetLastOpCode
15 15. F_CancelAction
16 16. F_Trace_File
17 17. F_Trace_Comment
18 18. F_Trace_ON
19 19. F_Trace_OFF

1. F_OpenInstancesAndFPAs

General Description

Multi API-DLL scans USB ports or LAN for connected FPAs listed in the setup file, or input string. When an FPA listed in the setup file is found, the corresponding API-DLL is copied on disk if necessary, and loaded. F_Initialization should be called for each FPA after this function succeeds.

Syntax

INT_X F_OpenInstancesAndFPAs( char * FileName )

Input

char * FileName : path to setup file, or list of serial numbers.

Valid FPAs-setup.ini setup file lists FPAs and SN pairs.

FPA-1 20150003
FPA-2 20180134
--or--
FPA-1 20090123
FPA-2 *	//any serial  number  (can  only be  done  at last line)

Valid FPAsIPs.ini, setup file lists FPAs by IP address:

FPAETH-IP-1 192.168.0.101
FPAETH-IP-2 192.168.0.102
FPAETH-IP-3 192.168.0.103
FPAETH-IP-4 192.168.0.104

Invalid example:

Valid list of serial numbers as a string:

translates to:

input string: "*# *" translates to:

In both cases, for the setup file and the input string, if a specified FPA is missing then it will not
affect subsequent entries. Therefore, a setup file with these contents:

and with FPA-3 missing (not connected, etc.) will initialize the Multi API-DLL to:

Output

INT_X : number of instances opened successfully

0 - failed

2. F_CloseInstances

General Description

All FPAs terminate communication with target devices and close target devices according to configuration settings (power setting, adapter line states, etc.). Finally, the USB/Ethernet connections to the FPAs are terminated and API-DLL instances are freed. The Multi API-DLL can now be used to open a new set of FPAs using the function F_OpenInstancesAndFPAs.

Syntax

Input

none.

Output

INT_X : success or failed

TRUE (1) - success
FALSE (0) - failed

3. F_Set_FPA_index

General Description

Select desired FPA index to perform specific tasks (access specific API-DLL instance).

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64, or 0 for all

Output

INT_X : success or error

TRUE (1), used FPA index is valid
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

IMPORTANT

Other functions that try to access this FPA index will also return FPA_INVALID_NO if this function was not called with a proper parameter.

4. F_Get_FPA_index

General Description

Get current FPA index.

Syntax

Input

none.

Output

BYTE : current FPA index as set using F_Set_FPA_index

5. F_Check_FPA_index

General Description

Get current FPA index and check if index is valid. A valid index corresponds to an individual FPA that has been opened with F_OpenInstancesAndFPAs. If FPA index was set to 0 (all), then this function will only return 0, even if no FPAs are open. Does not indicate whether FPA index is enabled or disabled.

Syntax

Input

none.

Output

INT_X : current fpa index if valid

current FPA index as entered using F_Set_FPA_index if selected FPA has been opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

6. F_Enable_FPA_index

General Description

Enable desired FPA index to accept commands. An FPA index is enabled by default. A disabled FPA index will ignore commands when the FPA index is set to it, or 0 (all FPAs).

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64

Output

none.

7. F_Disable_FPA_index

General Description

Disable desired FPA index to ignore commands. An FPA index is enabled by default. A disabled FPA index will ignore commands when the FPA index is set to it, or 0 (all FPAs).

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64

Output

none.

8. F_LastStatus

General Description

Return value from the last function call issued to the specified FPA (API-DLL instance). This function is useful when multiple FPAs are being programmed using FPA index 0 (all), but the return value was not the same for all FPAs (i.e. 4 FPAs succeeded, 1 FPA failed). When the return value is not the same for all FPAs then, then the actual return value from the Multi API-DLL will be FPA_UNMATCHED_RESULTS. To find out per FPA return values, select each FPA index individually using F_Set_FPA_index, and call F_LastStatus for each index.

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64.

Output

INT_X : Last return value from the selected FPA (API-DLL instance).

INT_X type return value from last function call on selected FPA
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

9. F_Multi_DLLTypeVer

General Description

Get Multi API-DLL software version number.

Syntax

Input

none.

Output

INT X : (DLL_ID) | (Version)

FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

10. F_Get_FPA_SN

General Description

Get serial number (SN) of FPA assigned to specified index.

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64

Output

INT_X : serial number

SN of selected FPA
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

11. F_Get_FPA_Label

General Description

Get detailed information of FPA assigned to specified index.

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64.

BYTE *label : pointer to instance of FPA_LABEL and bytes array, i.e.

Output

INT_X : serial number, hardware ID, meta-data

updated FPA_LABEL structure pointed to by label input parameter
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

Example of printing FPA_LABEL:

12. F_Get_FPA_List

General Description

This function will print the metadata about all avaialble FPAs that are connected to the computer, up to a maximum of 64 adapters.

Syntax

Input

ALL_FPA_LIST *FPA_List: pointer to array of ALL_FPA_LIST structs, i.e.

Output

INT_X : number of active adapters

13. F_GetProgressBar

General Description

Get internal progress counter value for operations done inside Encapsulated Functions . When used in conjunction with F_GetLastOpCode it allows the user application to keep track of progress in the same way that the FlashPro-M/GangPro-M GUI does.

Will return value between 0 and 100 for current sub-operation being performed inside encapsulated function. Depending on the complexity of the encapsulated function, the number of sub-operations will vary. Use F GetLastOpCode to get currently running sub-operation opcode. When transitioning from one sub-operation that reached a progress value of 100, to another sub-operation, the progress value will restart at 0. This will repeat until the last sub-operation upon which the progress value will remain at 100. A new invocation of an encapsulated function will restart the progress value at 0.

This function is thread-safe, therefore it can be called while the Multi API-DLL is busy, for example running F_AutoProgram. Intended usage is to call an encapsulated function with one thread, and repeatedly call this function and F_GetLastOpCode with another thread. When simultaneously programming using multiple FPAs (fpa index set to 0 (ALL FPAs), the thread monitoring progress can iterate different input parameters (fpa=1, fpa=2, fpa=3, etc.) to monitor the progress of each FPA individually. This function cannot be called with parameter 0 (ALL FPAs).

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64.

Output

INT_X : progress indicator

value between 0 and 100
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

Example

Refer to Multi API-DLL Functions | F_GetLastOpCode

14. F_GetLastOpCode

General Description

Read internal opcode value for sub-operations done inside Encapsulated Functions. When used in conjunction with F_GetProgressBar it allows the user application to keep track of progress in the same way that the FlashPro-M/GangPro-M GUI does.

Will return opcode for current sub-operation being performed inside encapsulated function. Depending on the complexity of the encapsulated function, the number of sub-operations will vary. Use F_GetProgressBar to get progress value between 0 and 100, of currently running sub-operation. When transitioning from one sub-operation that reached a progress value of 100, to another sub-operation, the progress value will restart at 0 and the opcode will be set to the new sub-operation, currently being run. This will repeat until the last sub-operation upon which the opcode will not change. A new invocation of an encapsulated function will reset the opcode to the first sub-operation of the new encapsulated function.

This function is thread-safe, therefore it can be called while the Multi API-DLL is busy, for example running F_AutoProgram. Intended usage is to call an encapsulated function with one thread, and repeatedly call this function and F_GetProgressBar with another thread. When simultaneously programming using multiple FPAs (fpa index set to 0 (ALL FPAs), the thread monitoring progress can iterate different input parameters (fpa=1, fpa=2, fpa=3, etc.) to monitor the progress of each FPA individually. This function cannot be called with parameter 0 (ALL FPAs).

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64.

Output

INT_X : opcode of currently running sub-operation

PROG_OPCODE_VERIFY_ACCESS (1) : FPA is attempting to perform action described in F_Verify_Access to MCU.
PROG_OPCODE_FLASH_ERASE (2) : FPA is attempting to perform action described in F_Memory_Erase.
PROG_OPCODE_FLASH_BLANK_CHECK (3) : FPA is attempting to perform action described in F_Memory_Blank_Check.
PROG_OPCODE_FLASH_SELECTED_BLANK_CHECK (4) : FPA is attempting to perform action described in F_Memory_Blank_Check when a subset of the memory space is selected in configuration settings.
PROG_OPCODE_FLASH_WRITE (5) : FPA is attempting to perform action described in F_Memory_Write.
PROG_OPCODE_FLASH_VERIFY (6) : FPA is attempting to perform action described in F_Memory_Verify.
PROG_OPCODE_FLASH_READ (7) : FPA is attempting to perform action described in F_Memory_Read.
PROG_OPCODE_LOCK_MCU (8) : FPA is attempting to perform action described in F_Lock_MCU.
PROG_OPCODE_UNLOCK_MCU (9) : FPA is attempting to perform action described in F_Clear_Locked_Device.
PROG_OPCODE_START_APP (10) : FPA is attempting to run application programmed onto target device (if enabled to be ran after F_AutoProgram in configuration settings).
FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

Example

Progress Bar Monitor

15. F_CancelAction

General Description

Function that will attempt to cancel any running Encapsulated Functions , like the GUI Cancel button. This function is thread-safe. One thread can call F_AutoProgram (for example) and another thread can call F_CancelAction to stop the first. A reinitialization is recommended using F_OpenInstancesAndFPAs after calling this function.

Syntax

Input

BYTE fpa : desired FPA index, 1 to 64.

Output

INT_X : success or failed

TRUE (1) - success
FALSE (0) - failed

16. F_Trace_File

General Description

Set custom FileName for trace (used with Trace_ON). Set append flag true to keep previous contents.

Syntax

Input

char *FileName : path to new trace file.
bool append : append to file if it already exists.

Output

INT_X : success or failed in opening file

TRUE (1) - success
FALSE (0) - failed

17. F_Trace_Comment

General Description

Append a custom comment to current trace file.

Syntax

Input

char *comment : comment to be added to trace file at current location in the trace.

Output

none.

18. F_Trace_ON

General Description

Activate tracing for subsequent calls to the Multi API-DLL. Log is saved in DLLtrace.txt located in the Multi API-DLL directory, or custom file if F_Trace_File function was called. When activated, records all API-DLL function calls from the application software invoked via the Multi API-DLL. The trace file is overwritten for each new session, unless the F_Trace_File append flag is true.