Dev:Link

link - Developer's guide to creating an application link DLL

GridLAB-D developers can create application link modules by coding the interface in C++.

Three functions must be exported to support the interface:


 * EXPORT bool init(link *lnk) : This function is called during the initialization process and must return true for GridLAB-D to continue.


 * EXPORT TIMESTAMP sync(link *lnk,TIMESTAMP t0) : This function is called each time the global clock changes or GridLAB-D iterates (in which case the clock does not change). The function must return TS_ERROR to halt GridLAB-D, TS_NEVER to allow GridLAB-D to halt at steady state, a future time t1 &gt; t0 to request a synchronization event at the time t1, or the time t0 to force GridLAB-D to iterate.


 * EXPORT bool term(link *lnk) : This function is called when the simulation is completed, either because of an error, because of steady state, or because the global clock has reached the stoptime.

C++ API
The following are defined in core/link.h.

link
The link class provides the complete specification and interface elements for an external application link.


 * LINKLIST *get_globals(void) : This function retrieves the first item in the list of globals.


 * GLOBALVAR *get_globalvar(LINKLIST *item) : Retrieves the item as a global variable.


 * LINKLIST *get_objects(void) : This function retrieves the first item in the list of objects.


 * OBJECT *get_object(LINKLIST *item) : Retrieves the item as an object.


 * LINKLIST *get_exports(void) : This function retrieves the first item in the list of variables to export.


 * OBJECTPROPERTY *get_export(LINKLIST *item)</tt> : Retrieves the item as an object property reference.


 * LINKLIST *get_imports(void)</tt> : This function retrieves the first item in the list of variables to import.


 * OBJECTPROPERTY *get_import(LINKLIST *item)</tt> : Retrieves the item as an object property reference.


 * char *get_name(LINKLIST *item)</tt> : This function is used to retrieve the name of an item.


 * char *get_next(LINKLIST *item)</tt> : This function is used to retrieve the next item in an item list.


 * char *get_data(LINKLIST *item)</tt> : This function is used to retrieve the GridLAB-D data associated with an item.


 * char *get_addr(LINKLIST *item)</tt> : This function is used to retrieve the address of the application data associated with an item.

LINKLIST
typedef struct s_linklist { char *name; // spec for link void *data; // local data void *addr; // remote data size_t size; // size of data size_t index; // index to data struct s_linklist *next; } LINKLIST;

OBJECTPROPERTY
typedef struct { OBJECT *obj; // object reference PROPERTY *prop; // property reference } OBJECTPROPERTY; gld_property(OBJECT*,PROPERTY*);

This structure is used to pair objects and properties for import and export items.

The gld_property class is used to obtain values for the variable.

Includes
You will need to include the target application's API definition headers and the GridLAB-D API header:


 * 1) include <core/gridlabd.h>

Libraries
You will typically need to include the target application's runtime interface link libraries.