Skip to content

stdlib-dll.md

Latest commit

 

History

History
214 lines (162 loc) · 6.63 KB

stdlib-dll.md

File metadata and controls

214 lines (162 loc) · 6.63 KB
Raw

Stdlib dll

The dll module provides comprehensive functionalities for loading, managing, and calling functions from dynamic-link libraries (DLLs) in the Windows environment, including memory management, error handling, and system API interactions.

Core Functions

new(dll_name)

Loads a dynamic-link library using lazy loading (loads on first use).

  • Parameters: dll_name - Name of the DLL file to load (string)
  • Returns: DLL object with procedure access
  • Example: kernel32 := dll.new("kernel32.dll")

load(dll_name)

Immediately loads a dynamic-link library.

  • Parameters: dll_name - Name of the DLL file to load (string)
  • Returns: DLL object with procedure access
  • Example: user32 := dll.load("user32.dll")

call_dll(dll_name, function_name, arguments...)

Directly calls a DLL function without creating a DLL object.

  • Parameters: dll_name - DLL name, function_name - Function name, arguments - Function arguments
  • Returns: Function result as integer
  • Example: result := dll.call_dll("kernel32.dll", "Beep", 500, 300)

DLL Object Functions

proc(function_name)

Retrieves a procedure address from the loaded DLL.

  • Parameters: function_name - Name of the function to retrieve (string)
  • Returns: Procedure object for calling the function
  • Example: message_box := user32.proc("MessageBoxW")

handle

Returns the handle to the loaded DLL.

  • Returns: DLL handle as integer
  • Example: handle := kernel32.handle

name

Returns the name of the loaded DLL.

  • Returns: DLL name as string
  • Example: name := kernel32.name

unload()

Unloads the DLL from memory (only for DLLs loaded with load()).

  • Returns: Boolean indicating success
  • Example: success := dll_obj.unload()

Procedure Object Functions

call(arguments...)

Calls the DLL function with the specified arguments.

  • Parameters: arguments - Function arguments (integers, floats, strings, bytes, booleans, null, or pointers)
  • Returns: Function result as integer
  • Example: result := add_func.call(3, 4)

name

Returns the name of the procedure.

  • Returns: Function name as string
  • Example: func_name := proc.name

addr

Returns the memory address of the procedure.

  • Returns: Function address as integer
  • Example: address := proc.addr

System Functions

last_error()

Gets the last error code from Windows API.

  • Returns: Last error code as integer
  • Example: error_code := dll.last_error()

free_library(handle)

Unloads a DLL from memory by handle.

  • Parameters: handle - DLL handle to unload
  • Returns: Boolean indicating success
  • Example: success := dll.free_library(handle)

get_proc_address(handle, proc_name)

Gets the address of a function in a loaded DLL.

  • Parameters: handle - DLL handle, proc_name - Function name
  • Returns: Function address as integer
  • Example: addr := dll.get_proc_address(handle, "FunctionName")

Memory Management

memory.alloc(size)

Allocates memory from the process heap.

  • Parameters: size - Number of bytes to allocate
  • Returns: Pointer object to allocated memory
  • Example: mem := dll.memory.alloc(1024)

memory.free(pointer)

Frees previously allocated memory.

  • Parameters: pointer - Pointer object to free
  • Returns: Boolean indicating success
  • Example: success := dll.memory.free(mem)

memory.copy(dest, src, size)

Copies memory between pointers.

  • Parameters: dest - Destination pointer, src - Source pointer, size - Number of bytes to copy
  • Returns: Boolean indicating success
  • Example: success := dll.memory.copy(dest_ptr, src_ptr, 100)

memory.read_string(pointer, max_len)

Reads a null-terminated string from memory.

  • Parameters: pointer - Pointer to string data, max_len - Maximum length to read
  • Returns: String read from memory
  • Example: text := dll.memory.read_string(str_ptr, 256)

Pointer Operations

pointer.create(address)

Creates a pointer object from an address.

  • Parameters: address - Memory address
  • Returns: Pointer object
  • Example: ptr := dll.pointer.create(0x12345678)

pointer.offset(pointer, offset)

Creates a new pointer with an offset from the original.

  • Parameters: pointer - Base pointer, offset - Byte offset
  • Returns: New pointer object
  • Example: new_ptr := dll.pointer.offset(ptr, 16)

pointer.read_int(pointer)

Reads a 4-byte integer from memory.

  • Parameters: pointer - Pointer to integer data
  • Returns: Integer value
  • Example: value := dll.pointer.read_int(int_ptr)

pointer.write_int(pointer, value)

Writes a 4-byte integer to memory.

  • Parameters: pointer - Pointer to write to, value - Integer value to write
  • Returns: Boolean indicating success
  • Example: success := dll.pointer.write_int(int_ptr, 42)

pointer.read_bytes(pointer, size)

Reads bytes from memory.

  • Parameters: pointer - Pointer to data, size - Number of bytes to read
  • Returns: Byte array
  • Example: data := dll.pointer.read_bytes(data_ptr, 100)

pointer.write_bytes(pointer, data)

Writes bytes to memory.

  • Parameters: pointer - Pointer to write to, data - Byte array to write
  • Returns: Boolean indicating success
  • Example: success := dll.pointer.write_bytes(data_ptr, byte_data)

Supported Argument Types

  • Integers: Passed directly as 32/64-bit values
  • Floats: Converted to integer representation (may lose precision)
  • Strings: Converted to UTF-16 and passed as pointers
  • Bytes: Passed as pointers to byte arrays
  • Booleans: Converted to 0 (false) or 1 (true)
  • Null: Passed as zero pointer
  • Pointers: Passed directly as memory addresses

Example Usage

Example DLL in C

// example_dll.c

#include <stdio.h>
#include <stdlib.h>

#ifdef _WIN32
#define EXPORT __declspec(dllexport)
#else
#define EXPORT
#endif

EXPORT int add(int a, int b) {
    return a + b;
}

Loading and Using the DLL in Tender

// example.td
import "dll"

// Load the DLL
my_dll := dll.load("example_dll.dll")

// Get the 'add' function from the DLL
add_func := my_dll.proc("add")

// Call the 'add' function with arguments
result := add_func.call(3, 4)

// Print the result
println("Result of addition:", result)  // Output: Result of addition: 7

How to compile dll

  1. Compile the C code into a DLL. For example, using MinGW on Windows:

    gcc -shared -o example_dll.dll example_dll.c

  2. Load and use the DLL in Tender as shown in the example above.

    tender test_dll.td