OSDynLoad_IsModuleLoaded

Syntax

#include <cafe/os/OSDynLoad.h>

int OSDynLoad_IsModuleLoaded(char const * apBaseModuleName,
			     OSDynLoad_ModuleHandle * apRetHandle);

Parameters

apBaseModuleName Base module name (no path or extension) to check if it is loaded.
NOTE:
If the module's base file name (not including its extension) includes a "." character, then the extension must be included. For example, if a module's full file name is system.dll.rpl, then the full file name must be passed.
apRetHandle Pointer to the handle variable to receive the handle to the loaded module. This handle value is used in other OSDynLoad function calls.  If the module is already loaded, the result is 0 and a nonzero handle to the existing module is returned. If the result and handle are both 0, then there were no errors with the parameters and the module was not loaded. If the function returns a nonzero result, there is an issue with the parameters and the handle will be 0.

Return Values

Returns an OSDYNLOAD_ERR_xxx error code (see OSDynLoad.h).

The following table lists the most common errors that might be returned.

Error Cause Possible Solution
OSDYNLOAD_ERR_BAD_HANDLE_RETURN_POINTER
-1160708079
0xBAD10011
apRetHandle is NULL (or 0). Ensure that the argument points to valid memory.
OSDYNLOAD_ERR_NULL_FILENAME
-1160708081
0xBAD1000F
apBaseModuleName is NULL (or 0). Ensure that the argument points to valid file name.
OSDYNLOAD_ERR_EMPTY_FILENAME
-1160708080
0xBAD10010
apBaseModuleName[0] is NULL (or 0). Ensure that the argument points to valid file name.
OSDYNLOAD_ERR_NO_FILENAME
-1160708078
0xBAD10012
apBaseModuleName[0] is not file name. For example "path/". Ensure that the argument points to valid file name.
OSDYNLOAD_ERR_SYS_HEAP_MEMORY_ALLOCATION_FAILURE
-1160708049
0xBAD1002F
Not enough memory in the system heap. Use makerpl's -h option to increase the size of system heap.

NULL (or 0) is never a valid handle return value.  If the function fails, the return handle value will always be set to 0 unless the pointer to the handle itself is not a valid pointer.

Description

This function is a special purpose RPL function. The function takes the base module name to load, and returns a handle to the loaded module. It does not load a module if it is not loaded.

This function returns the handle to any module already loaded regardless of which module loaded it. For example, game.rpx loads mario.rpl and mario.rpl loads luigi.rpl. If game.rpx calls OSDynLoad_IsModuleLoaded for luigi.rpl, game.rpx can use the handle with calls to OSDynLoad_FindExport.

It is not recommended to use the target module's handle returned by OSDynLoad_IsModuleLoaded with OSDynLoad APIs unless you know that the module making the OSDynLoad_IsModuleLoaded call either imported the target module or used OSDynLoad_Acquire to acquire the target module and it is understood that it will not be released. Unless such care is exercised, perhaps a call to OSDynLoad_Release could release the target module before you are finished using it. In the above example, there could be runtime issues if game.rpx called OSDynLoad_Release with the handle for luigi.rpl and later, mario.rpl calls one of luigi.rpl's functions. The possible issues are averted if you follow the call to OSDynLoad_IsModuleLoaded with a call to OSDynLoad_Acquire (see example below).

We anticipate at least the following uses for OSDynLoad_IsModuleLoaded:

int err;
OSDynLoad_ModuleHandle handle;

err = OSDynLoad_IsModuleLoaded("sndcore2", &handle);
if (!err && handle) {
    err = OSDynLoad_Acquire("sndcore2", &handle);
} else {
    err = OSDynLoad_Acquire("snd_core", &handle);
}
if (err) {
    /* error handling here */
}

Do Not Call From

None.

See Also

OSDynLoad_Acquire
OSDynLoad_AddNotifyCallback
OSDynLoad_DelNotifyCallback
OSDynLoad_FindExport
OSDynLoad_FindTag
OSDynLoad_GetAllocator
OSDynLoad_GetLoaderHeapStatistics
OSDynLoad_GetModuleName
OSDynLoad_Release
OSDynLoad_SetAllocator
makerpl

Revision History

2014/02/27 Note that a file name with a "." must include the extension.
2013/11/07 Use example.
2013/11/01 Initial version.


CONFIDENTIAL