3rd Party DLL Support
- From EDD 10.1, EDD supports loading a 3rd party standard DLL (Dynamic Link Library, a form of portable application extensions)
- From EDD 11.6, and EDDLite 1.0.0, EDD supports loading c# assemblies and their dependencies DLLs.
- From EDD 16.1 EDD supports external DLLs providing user panels which can act as standard user panels.
DLLs are loaded from the appdata's DLL folder (%%LOCALAPPDATA%% \ programname \DLL). You can remove the DLL either by deleting the action pack that it came with, deleting all files in this folder, or using Safe Mode to delete all DLLs.
You can disable DLLs by using settings | DLL Permissions, or use Admin | DLL permissions menu.
Any new DLLS loaded by EDD/EDDLite are confirmed for use by a pop up dialog asking the user if it is safe to use them. Users must be aware of where the DLL comes from and use their own judgement if to use it.
This repository on git has an examples for:
- CSharpDLL - a simple C# DLL dependent on a sub project Dependency c# DLL to demonstrate c# dependency DLL loading)
- CSharpDLLPanel - a demonstration of a external user panel that integrates into the panel system of EDD and appears as another panel option on the selector
- A Win64DLL (C++ DLL)
- A C# test harness to call these DLLs (not user panel functionality)
The test harness loads DLLs from the ExampleAddInDLL\appdata folder, and the ExampleAddInDLL\x64\debug folder.
The Win64DLL project demonstrates a DLL in C++. The EDInterface.h is the standard header with the EDD interface definition for C++. EDDInterface.cpp is the DLL code, and reacts to calls from EDD/EDDLite and writes a file out to c:\code\eddif.txt to demonstrate output from EDD.
The interface between C++ and EDD is here
The CSharp DLL demonstrates a c# assembly and its interfaces to EDD/EDDLite.
The interface between c# and EDD is defined here and compiled into a C# DLL.
An c# assembly needs a reference to be added to the EDDDLLInterfaces assembly .dll, which is included in the EDDDLLInterfaces folder. This defines common structures/classes between the EDD/EDDLite program and the assembly. This DLL is generated by the ELiteDangerousCore project and is copied in as just the .dll into the example project.
The interface DLL is referenced in the TestHarness and CSharpDLL projects under Add References | Browse option.
Has the same interfaces as per the standard C# DLL, but implements a Winforms.UserControl DemonstrationUserControl, implementing the IEDDPanelExtension defined in EDDDLLInterfaces.dll. See below.
In c#, its defined by the EDDDLLInterfaces project in the EliteDangerousCore. For C++ DLLs, its defined by the EDInterface.h header. These are calls from EDD to the DLL to initialise, close, configure and provide information.
Calls run in the main UI thread of EDD so keep it short!
- EDDInitialise(string verflags, string dllfolder, EDDCallBacks callbacks)
Called on initialisation. Verflags is a semicolon list of version [;flags].. See the EDDInterface.cs file in EliteDangerousCore for definitions.
The callbacks define a structure containing calls the DLL can make back to EDD/EDDLite.
- EDDRefresh(string commander, JournalEntry last_je)
Called when a commander has been loaded.
- EDDNewJournalEntry(JournalEntry last_je)
Called when a new journal entry has been received. EDD Filtering and merging has been performed on this, see the unfiltered version for the raw journal stream.
- EDDNewUIEvent(string json)
Called when a new UI Event has been received. See EliteDangerousCore\UIEvents for definitions of events. The JSON string contains the UI events class data.
- EDDActionCommand( string cmdname, string[] parameters) [EDD only]
An EDD action script has asked the DLL to perform a command with parameters
- EDDActionJournalEntry( JournalEntry entry) [EDD only]
An EDD action script has passed a journal entry to the DLL
- EDDTerminate
EDD/EDDLite is terminating.
- string EDDConfig (string configin, bool editit) [EDD only]
Called after Initialisation, with editit=false, it passes in a configuration string from EDD which was last saved (or "") and then saves the configuration string coming back from the function. Also called with editit=true if the user has asked via the settings page for a configuration change.
The string can be anything, JSON, discrete text etc.
- EDDNewUnfilteredJournalEntry(JournalEntry je)
Passed unfiltered (all journal entries raw from the journal file, unmerged and unfiltered) to the DLL.
- EDDMainFormShown()
Called when main form is on screen
- EDDDataResult(object requesttag, object usertag, string data)
Called by EDD due to a request for data.
The EDDInitialise provides a callback pointer, which can be used to request data from EDD by the DLL.
Data is sent to the panel in some calls in JSON, extracted from the EDD structures using serialization. Note the .cs comment on being defensive about these- they may change if absolutely required.
- RequestHistory(long index, bool isjid, out JournalEntry f) [EDD only]
Request journal entry index (either 1..total records or the jid of the record)
- RunAction(string name, string paralist) [EDD only]
Generate an action event name, with the parameters given (in the form x=value,y=value). The loaded action scripts will be presented with the event for them to process.
- GetShipLoadout(string name) [EDD only]
Get the current ship loadout as JSON (name = blank) or a named ship (by type or user ident)
- AddPanel(string id, Type paneltype, string wintitle, string refname, string description, System.Drawing.Image img) [EDD c# DLL only]
Add a panel. Must be called during EDDInitialise only.
- GetTarget [EDD Only]
Get target as JSON
- WriteToLog [EDD only]
- WriteToLogHighlight [EDD only]
Write to log window [EDD only]
- RequestScanData(object requesttag, object usertag, string system, bool edsmlookup) [EDD c# DLL only]
Request scan data. Data will be returned by EDDDataResult call.
- GetSuitsWeaponsData [EDD only]
Return json of this data
- GetCarrierData [EDD only]
Return json of this data
- GetVisitedList [EDD only]
Return json of visited stars list, in visit order
- GetShipyards [EDD only]
Return json of shipyard info
- GetOutfitting [EDD only]
Return json of outfitting info
An external DLL panel is registered with EDD during EDDInitialise (only) by calling the EDD callback AddPanel.
The DLL implements a winform user control, with the IEDDPanelExtension interface.
Calls to the panel run in the main UI thread of EDD so keep it short!
The interface has a set of panel lifetime functions which are called during panel creation (as defined in the UCCB contract https://github.com/EDDiscovery/EDDiscovery/blob/master/EDDiscovery/UserControls/UserControlCommonBase.cs):
- Initialise
- SetTransparency
- LoadLayout
- InitialDisplay
- AllowClose
- Closing
And a set of interfaces which provide details on journal and UI events
- HistoryChanged
- NewUnfilterdJournal
- NewFilteredJournal
- NewUIEvent
These duplicate the EDD interfaces above, but provide a more panel orientated method of obtaining the data.
Other interfaces as detailed in the EDDDLLInterfaces.cs file.
A callback interface set is provided using panel Initialise so data and status may be requested, and persistent data for the panel saved into EDD (using PanelSave* functions).
The obsolete now EDMC harness demonstrates a python plugin. A C# DLL is written, as in here which implements the c# interface to EDD.
On EDDInitialise, the code searches for the python plugin and runs it, using the python that it can find on the machine. PythonLauncher.cs shows how the code finds python.
The code is complicated by the need to be able to run console, windows, run the python .exe or run from script (controlled by runfrom.txt). A system which just ran python scripts would be simpler.
EDD Refresh, New Journal Entry, UI events etc are fed through to the python plugins via file writes as its transfer medium.
(C) 2015-2023 EDDiscovery Team