DLL Common Specifications

This specification defines a common interface for DLL modules used in SHIORI, SAORI, and other systems.

Memory management

All argument/return value processing is performed using Windows Global Memory. Specifically, the following procedure is used:

The baseware allocates memory and writes data by specifying the GMEM_FIXED flag to GlobalAlloc()
The module casts the received HGLOBAL to (char*) to access the data directly
The module refers to the len parameter to get the data length and reads the required data
Module frees memory with GlobalFree()
When returning the result of processing, the module allocates memory for the new GMEM_FIXED designation with GlobalAlloc()
The module writes the result to the allocated memory and sets len to the new data length
The baseware releases the returned memory handle with GlobalFree() after use

Important notes:

GlobalLock()/GlobalUnlock() is not necessary when using GMEM_FIXED flag
Direct memory access is possible by casting HGLOBAL to (char*)
Since the memory passed is not guaranteed to be null-terminated, always refer to the len parameter to limit the access range
Memory for return values should be zero-terminated by allocating one byte more than len to ensure robust operation independent of the baseware implementation

request function

extern "C" __declspec(dllexport) HGLOBAL __cdecl request(HGLOBAL h, long *len);

All requests are made through a single function, request, which is the primary interface to the module and handles all requests from the baseware.

The request data format is designed with reference to the HTTP and SSTP header formats, and follows the rules below:

All lines are separated by CR+LF (0x0D, 0x0A)
The first line should contain the command name and protocol version
The secone and subsequent lines are followed by an arbitrary number of headers in the format "header name: value"
The end of the header section is indicated by placing two consecutive CR+LF (adding a blank line)
Character encoding follows the scheme specified in the header (typically UTF-8 or default OEM codepage)

Life cycle functions

The following functions are called when loading and unloading DLLs.

loadu function

extern "C" __declspec(dllexport) BOOL __cdecl loadu(HGLOBAL h, long len);

Function to initialize the module.
The first argument, global memory, contains the module's directory path in UTF-8 encoding.

Implemented since SSP 2.6.92 (2025/1/16). Prior to that, only "load" was implemented.

Example of processing content:

Load the necessary data files using the passed path as the current directory
Initialize resources required for module operation
Initialize log files and databases as needed

Important notes:

Always release passed global memory even when string data is not needed
Returns TRUE if initialization succeeds, FALSE if it fails
This function is preferentially used by baseware

load function

extern "C" __declspec(dllexport) BOOL __cdecl load(HGLOBAL h, long len);

Previous version of the loadu function.
Same specification as the loadu function, except that the module directory path of the first argument is encoded in the default OEM codepage (CP932 in a Japanese environment).

Important notes:

Used as a fallback designation when the loadu function is not implemented
For compatibility, it is desirable to implement both "load" and "loadu", and ignore "load" if it is called when "loadu" is already initialized
For Unicode support, the received path must be converted to a full-width string where appropriate

unload function

extern "C" __declspec(dllexport) BOOL __cdecl unload();

Function to handle module termination. This function is called by the baseware when a module is unloaded.

Processes that should be implemented:

Release a file handle opened by CreateFile, etc.
Release synchronization objects created by CreateMutex, etc.
Wait for threads created by CreateThread, etc., to finish and perform post-processing
Release all other system resources reserved by the module

The return value is not currently used, but should return TRUE for future expandability.