DosGetResource

From EDM2
Jump to: navigation, search

Returns a pointer to a specified resource.

Syntax

DosGetResource (hmod, idType, idName, ppb)

Parameters

hmod (HMODULE) - input
Handle of module that has the required resource.
A value of zero means to get the address from the current process. A value other than zero is a module handle that was returned by DosLoadModule.
idType (ULONG) - input
The type identifier of the 32-bit resource.
This value must be in the range of 0x0000 to 0xFFFF.
idName (ULONG) - input
The name identifier of the 32-bit resource.
This value must be in the range of 0x0000 to 0xFFFF.
ppb (PPVOID) - output
A pointer to the resource.

Return Code

ulrc (APIRET) - returns
DosGetResource returns one of the following values:
  • 0 NO_ERROR
  • 6 ERROR_INVALID_HANDLE
  • 87 ERROR_INVALID_PARAMETER

Remarks

DosGetResource returns the address of the specified resource object.

Resource objects are read-only data objects that can be accessed dynamically at run time. The access key is two 32-bit numbers. The first number is a type ID; the second, a name ID. These are similar to the file extension and file-name portions of a file name.

Resource objects are placed into an executable file by the Resource Compiler (RC.EXE).

If a STRINGTABLE or MESSAGETABLE resource is specified in an RC file, with a number of IDs and respective strings, these RT_STRING or RT_MESSAGE string resources are bundled together in groups of 16. Any missing IDs are replaced with zero length strings. Each group, or bundle, of RT_STRING or RT_MESSAGE resources is assigned a unique sequential ID. The resource string ID is not necessarily the same as the ID specified when using DosGetResource. The formula for calculating the ID of the resource bundle, for use in DosGetResource, is as follows:

bundle ID = ( id / 16) +1

where id is the string ID assigned in the RC file.

Thus, bundle 1 contains strings 0 to 15, bundle 2 contains strings 16 to 31, and so on. Once the address of the bundle has been returned by DosGetResource (using the calculated ID), the buffer can be parsed to locate the particular string within the bundle. The number of the string is calculated by the formula:

string = id % 16

(string = remainder for id/16).

The buffer returned consists of the CodePage of the strings in the first USHORT, followed by the 16 strings in the bundle. The first BYTE of each string is the length of the string (including the null terminator), followed by the string and the terminator. A zero length string is represented by two bytes: 01 (string length) followed by the null terminator.

Example Code

This example loads the dynamic link module "DISPLAY.DLL," gets a resource object from it, and then releases it.

#define INCL_DOSRESOURCES     /* Resource types */
#define INCL_DOSMODULEMGR     /* Module Manager values */
#define INCL_DOSERRORS        /* DOS error values */
#include <os2.h>
#include <stdio.h>

int main(VOID) {
UCHAR     LoadError[256] = "";         /* Area for Load failure information */
PSZ       ModuleName = "C:\\OS2\\DLL\\PMWP.DLL";  /* DLL with resources */
HMODULE   ModHandle  = NULLHANDLE;        /* Handle for module */
PVOID     ResPtr     = NULL;              /* Pointer to resource */
APIRET    rc         = NO_ERROR;          /* API return code */

 rc = DosLoadModule(LoadError,               /* Failure information buffer */
                    sizeof(LoadError),       /* Size of buffer             */
                    ModuleName,              /* Module to load             */
                    &ModHandle);             /* Module handle returned     */
 if (rc != NO_ERROR) {
    printf("DosLoadModule error: return code = %u\n", rc);
    return 1;
 }

 rc = DosGetResource(ModHandle,     /* Handle for DLL containing resources */
                     RT_POINTER,    /* Ask for  Pointer                    */
                     1L,            /*          with an ID of 1            */
                     &ResPtr);  /* Get back pointer                    */
 if (rc != NO_ERROR) {
    printf("DosGetResource error: return code = %u\n", rc);
    return 1;
 } else {
    printf("Resource pointer = 0x%x\n", ResPtr);
 } /* endif */

 rc = DosFreeResource(ResPtr);
 if (rc != NO_ERROR) {
    printf("DosFreeResource error: return code = %u\n", rc);
    return 1;
 }

return NO_ERROR;
}

Related Functions