dna 0.6.1

Dart Native Access lets you deal with native libraries from Dart with zero lines of C/C++ code. Just pure Dart.

DNA

Dart Native Access lets you deal with native libraries from Dart with zero lines of C/C++ code. Just pure Dart.

How to ...

For instance, you want to call getppid function from libc library on Linux.

• Find method signature in documentation:

pid_t getpid(void);

• Map parameters types and return type to C data types:

typedef int pid_t;

• Map C data types to Dart types and DNA type constants. See Type mapping.

• Define class Libc with annotation @Library:

@Library('libc.so.6')
class Libc {
  
}

libc.so.6 is library name.

• Define method getppid. Annotate parameters with @Param and method with @Method with corresponding type constants:

class Libc {
  int getpid();
}

In this example method has no parameters.

• Finish with boilerplate code:

class Libc extends DynamicLibrary<Libc> {
  int getpid();
}

• Use it

Libc libc = new Libc();
var processId = libc.getpid();

For full code see Examples.

How to define library

@Library('name')
class Library DynamicLibrary<Library> {
    
}

name is the OS specific library name. For instance: libname.so or name.dll or libname.dylib.

Please see documentation for the target OS to know where dynamic linker searches for the library.

• Linux - dlopen
• Mac OS - dlopen
• Windows - LoadLibrary

FIXME: Symlinks aren't supported

How to define method

@Method(C_XYZ) T method(
  @Param(C_XYZ) T1 inParam, 
  @Param(C_XYZ, out: true) Ref<T2> outParam);

Annotation @Method is used to define C type of return value. Annotation @Param is used to define C type of paramters. C_XYZ is C type constant. See Type mapping. @Method and @Param are optional. See Default mapping.

How to define structure

@Struct()
class Struct {
    @Field(C_XYZ) T field;
}

Annotation @Struct is used to define C struct. Annotation @Field is used to define field of C struct. @Field is required. All fields without @Field annotations are ignored.

Type mapping

Basic types

C	Dart	Constant
void	void	VOID
char	int	C_CHAR
short	int	C_SHORT
uchar	int	C_UCHAR
ushort	int	C_USHORT
int	int	C_INT
uint	int	C_UINT
long	int	C_LONG
ulong	int	C_ULONG
longlong	int	C_LONGLONG
ulonglong	int	C_ULONGLONG
bool	bool	C_BOOL
float	double	C_FLOAT
double	double	C_DOUBLE

Fixed-width types

C	Dart	Constant
int8_t	int	C_INT8
uint8_t	int	C_UINT8
int16_t	int	C_INT16
uint16_t	int	C_UINT16
int32_t	int	C_INT32
uint32_t	int	C_UINT32
int64_t	int	C_INT64
uint64_t	int	C_UINT64

Pointers

C	Dart	Constant	In/Out	Comments
char *	String	C_STRING	In
char *	Ref<String>	C_STRING	Out	String must be initialized and have expected by callee size.

char **	List<String>	LISTSTRING	In
{integer type} *	List<int>	C_{type}	In
{integer type} *	Ref<List<int>>	C_{type}	Out
{decimal type} *	List<double>	C_{type}	In

{decimal type} *	Ref<List<double>>	C_{type}	Out
{type} *	int	C_POINTER	In	Raw pointer value.
{type} *	TypedData	TYPEDDATA	In/Out	TypeData must be initialized and have expected by callee size.

Structs

C	Dart	Constant	In/Out	Comments
struct *	T	C_STRUCT	In/Out	T is struct class. See Define structure.

Default mapping

Dart	C	Constant
void	void	VOID
int	int	C_INT
bool	bool	C_BOOL
double	float	C_FLOAT

Out parameters

If parameter modified by callee it must be marked as @Param(..., out: true)

Dart doesn't support parameters by reference. It's good but it's the cause of one challenge: callee cannot override parameter object. For instance, String parameter cannot be modified inside called method.

Therefore, it's needed to use wrapper object to emulate out parameters: Ref<T>.

FIXME: Describe pointers, in/out parameters, String parameters and TypedData parameters

FAQ

• I see Failed assertion: 'libraryPointer != 0

Dynamic linker cannot find the library. Check the library name.

• I see Failed assertion: 'methodPointer != 0

Dynamic linker cannot find method in the library. Check the method name. Check that library exports the method.

• My library is cross platform and has different name on each platform.

See example.

@Library('libname.so', 'name.dll')
class Library DynamicLibrary<Library> {

}

• My library doesn't export functions or/and uses custom logic to get function pointer

See example.

@Library('name.dll')
class Library DynamicLibrary<Library> {
  Library() : super(getMethodPointer);

  static int getMethodPointer(DynamicLibrary that, Invocation invocation) {
    return ... //raw function pointer here
  }
}

Examples

Linux

libc library

@Library('libc.so.6')
class Libc extends DynamicLibrary<Libc>  {
  int getpid();

  int getuid();
  
  int getgid();

  int getgroups(int count, @Param(C_INT) Ref<List<int>> groups);
  
  int rand();
  
  int rand_r(@Param(C_INT) Ref<List<int>> seedp);
  
  void srand(@Param(C_UINT) int seed);
}

void main() {
  var libc = new Libc();

  var processId = libc.getpid();
  print('pid $processId');

  var userId = libc.getuid();
  print('user id ${userId}');

  var groupId = libc.getgid();
  print('group id ${groupId}');

  var n = libc.getgroups(0, new Ref(new List()));
  var groups = new Ref(new List<int>.filled(n, 0));
  libc.getgroups(n, groups);
  print('groups ${groups.value}');

  libc.srand(0xDEADBEEF);
  var rand = libc.rand();
  print('random $rand');

  var seed = new Ref([0xDEADBEE]);
  var srand = libc.rand_r(seed);
  print('random with seed $srand');
}

Windows

kenel32 library

@Library('Kernel32')
class Kernel32 extends DynamicLibrary<Kernel32> {

  static const int DWORD = C_ULONG;
  static const int HANDLE = C_POINTER;
  static const int HMODULE = HANDLE;  
  static const int PSIZE_T = C_POINTER;
  
  @Method(HANDLE)
  int GetCurrentProcess();

  @Method(DWORD)
  int GetProcessId(
    @Param(HANDLE) int process);

  @Method(DWORD)
  int GetModuleFileNameA(
      @Param(HMODULE) int process,
      @Param(C_STRING) Ref<String> imageFileName,
      @Param(DWORD) int size);

  bool GetProcessWorkingSetSize(
      @Param(HANDLE) int process,
      @Param(PSIZE_T) Ref<List<int>> minimumWorkingSetSize,
      @Param(PSIZE_T) Ref<List<int>> maximumWorkingSetSize);

  @Method(DWORD)
  int GetLastError();
}

void main() {
  Kernel32 kernel32 = new Kernel32();
  var process = kernel32.GetCurrentProcess();
  var processId = kernel32.GetProcessId(process);
  print('pid $processId = ${io.pid}');

  var min = new Ref([0]);
  var max = new Ref([0]);
  kernel32.GetProcessWorkingSetSize(process, min, max);
  print('working set min ${min.value} max ${max.value} error ${kernel32.GetLastError()}');

  var name = new Ref<String>(new String.fromCharCodes(new List.filled(64, 0)));
  var length = kernel32.GetModuleFileNameA(0, name, name.value.length);
  print('module name ${name.value.substring(0, length)} error ${kernel32.GetLastError()}');
}

Please find more examples in examples/.

Requirements

• Linux 64-bit
• Windows 64-bit

To Do

• Improve performance
• A lot of things aren't supported yet
  • Function pointers to Dart methods
  • Custom structure align
  • Unions
  • ...
• Mac OS support
• Refactor and clean up code