The MicroStation Resource Manager provides the applications programmer with a number of functions that allow the user to read (load), modify, write, create and delete resources to and from resource files. These are the low level functions used by the other subsystems mentioned above and are the only safe direct interface to resources. The following sections discuss various aspects of resource file and resource item management.
Resource File Management
In order to reference any resources, an application must have access to the resource file containing those resources. An application gains access to resources through three methods:
- Opening resource files using the mdlResource_openFile function.
- By "importing" the resource handle from another task.
- Inheriting them from parent tasks.
An application can open as many resource files as it needs for its processing. It can also open resource files currently opened by another task within MicroStation. Although an application does not necessarily need to keep track of the resource file handles after opening the files, the handle is required for applications to load a resource from a specific file and to close or add resources to a file. In most cases, an application will simply call mdlResource_openFile upon entry to main function and mdlResource_closeFile prior to exiting the application as shown below:
For most applications, no additional mdlResource_... function calls are needed to perform any resource references, as this is handled by the various subsystem managers.In cases where the application needs to update resource information in a file, it must open the file for Read / Write access by passing RSC_READWRITE as the last parameter to mdlResource_openFile.
The mdlResource_createFile function allows the user to create new resource files.This function is useful to applications which need to maintain application specific user preferences or other information in a separate file. Remember that this function does not open the file; mdlResource_openFile must be called after this function to place resources into the file.
Loading and querying resources
When an application wants to load a resource from a resource file into memory for use, it uses one of the Resource Manager load functions. These functions provide differing levels of access to the resource information in a resource file. On occasion, it may be necessary to retrieve information about resources and resource files. The mdlResource_query... functions provide this capability. An additional query function is also provided to return information about resources already loaded by the application program.
Loading Resources
Typically, an application doesn't care where a resource is found (i.e., which file it came from) since all of the resources specific to the application are typically placed in their own resource files and any other resources it uses it expects to inherit from its parents. This being the case, an application will typically use the mdlResource_load and mdlResource_loadWString functions specifying NULL as the resource file handle. This has the effect of causing the MicroStation Resource Manager to start looking for the specified resource in the application's resource files and then resource files in the order of most recently opened first until it locates the resource requested. Once the resource is found, it is loaded into memory and the address of the resource is returned to the application. If the resource is not found, NULL is returned to the application. This is shown graphically in the diagram below.
It is important to remember that resources loaded into memory with the mdlResource_load function must be freed using mdlResource_free when the application is done with the resource. If the requested resource was not previously loaded by the Resource Manager, mdlResource_load will load the requested resource into memory allocated by the Resource Manager as it is read from the file and return the address of the resource to the application program. This action is performed only once. If the resource was already loaded, the Resource Manager will simply return the address of the loaded resource to the application.
The mdlResource_loadWString function is a specialized version of the mdlResource_load function which allows the application to extract a single string out of a message list resource without loading the message list resource and extracting the string itself. Since only the string from the message list is returned, the application does not need to free the resource from memory.
The other function which can be used to load resources into memory is the mdlResource_directLoad function. This function does not perform the resource load operation, but instead gives the application program information about the resource so that the application can perform its own resource file loading. The first three parameters of this function are the same as those for the mdlResource_load function. A fourth parameter is passed to this function which is a pointer to a structure into which the function returns the necessary information for the application to read the resource. This structure is defined in rscdefs.h and shown below.
Once the application has this information, it can read the resource file itself instead of relying on the Resource Manager to read the resource.This gives the application complete control of the resource and the memory it occupies.The application does not have to be concerned about more of the resource being read than it needs or keep the resource file open after the resource has been read.The application does need to allocate the memory into which the resource is read.
Querying Resource Information
Four functions are provided for retrieving information about resources and resource files. These functions provide a tiered query structure in which an application can query:
- Resource File Information - Using mdlResource_queryFile and mdlResource_queryFileHandle, an application can query the number of different resource classes and obtain a list of the resource classes in a file. Additionally, they can query for a version and identity of the resource file.
- Resource Class Information - Using mdlResource_queryClass, an application can query the number of resources in a specific class and the resource IDs for each resource instance in a specific class in the resource file. An application can also request the alias of a specific resource instance and the next available resource ID which can be used in the resource file for that class.
- Resource Information - Using mdlResource_query, an application can query the size, type (class), resource ID, source resource file handle, alias and source resource file name for the specified resource.
This information can be useful for applications which may need to perform lookups and or processing of multiple resources and files. A sample section of code below shows the use of these functions. This function locates all resources of a specified class in a specified resource file and returns information about both the resource file (the file handle) and the resource located. It returns information about one resource at a time.