ResourceManagement

This is used to add a new resource to a resource file. More...

Functions
StatusInt	mdlResource_addByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, void *pRsc, size_t rscSize, WCharCP pAlias)
StatusInt	mdlResource_changeAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Allows an application assign a new alias name to a resource. More...
StatusInt	mdlResource_createFileForPlatform (WCharCP pFilename, CharCP pIdent, UInt32 version, UInt32 platformId)
	This is used to generate a new resource file. More...
StatusInt	mdlResource_directAdd (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias, RscDirectAccess *pDirect)
	Gives the MDL programmer full control of writing resources to a resource file. More...
StatusInt	mdlResource_directAddComplete ()
	Use this function to inform the resource manager that a new resource was added with mdlResource_directAdd. More...
StatusInt	mdlResource_getRscIdByAlias (RscId *pRscId, RscFileHandle rfHandle, RscType typeId, WCharCP pAlias)
	Obtains a resource's identification number from its ASCII alias name. More...
StatusInt	mdlResource_queryFile (UInt32 *pReturnValue, WCharCP pFilename, long queryId)
	Queries the resource manager for information regarding a resource file. More...
void *	mdlResource_resize (void *pResource, size_t newSize)
	Adjusts the size of a resource in a file. More...
StatusInt	mdlResource_add (RscFileHandle rfHandle, RscType typeId, RscId rscId, void *pRsc, size_t rscSize, WCharCP pAlias)
	Used to add a new resource to a resource file. More...
void	mdlResource_closeFile (RscFileHandle rfHandle)
	Closes a resource file. More...
StatusInt	mdlResource_createFile (WCharCP pFilename, CharCP pIdent, UInt32 version)
	Used to generate a new resource file. More...
StatusInt	mdlResource_delete (RscFileHandle rfHandle, RscType typeId, RscId rscId)
	Deletes a resource with a given resource ID from a resource file. More...
StatusInt	mdlResource_deleteByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Deletes a resource with a given resource ID from a resource file. More...
long	mdlResource_directLoad (RscFileHandle rfHandle, RscType typeId, RscId rscId, RscDirectAccess *pDirect)
	Allow the application control of resource loading. More...
StatusInt	mdlResource_free (void *pResource)
	Removes a resource from memory. More...
void *	mdlResource_load (RscFileHandle rfHandle, RscType typeId, RscId rscId)
	Used to load resources from an opened resource file. More...
void *	mdlResource_loadByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Used to load resources from an opened resource file. More...
StatusInt	mdlResource_openFile (RscFileHandle *pRfHandle, WCharCP pFileName, UInt32 fileAttributes)
	Opens a resource file, making its contents available to the application using subsequent mdlResource_... More...
StatusInt	mdlResource_query (void *pReturnValue, void *pResource, long queryId)
	Queries the resource manager for information regarding a resource. More...
StatusInt	mdlResource_queryClass (void *pReturnValue, RscFileHandle rfHandle, RscType typeId, long queryId, void *pArg)
	Queries the resource manager for information regarding a resourceclass. More...
StatusInt	mdlResource_queryClassByAlias (void *pReturnValue, RscFileHandle rfHandle, RscType typeId, long queryId, void *pArg, WCharCP pAlias)
	Queries the resource manager for information regarding a resourceclass. More...
StatusInt	mdlResource_write (void *pResource)
	Writes an updated resource (obtained with mdlResource_load) to its original position in the resource file from which it was loaded. More...
StatusInt	mdlResource_queryFileHandle (void *pReturnValue, long retValSize, RscFileHandle rfHandle, long queryId, void *pArg)
	Queries the resource manager for information regarding an open resource file (or files). More...
END_EXTERN_C StatusInt	mdlResource_loadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc *m=NULL)
	Copies the wide character string identified by listId and stringNum into the WString referenced by outString. More...
StatusInt	mdlResource_loadWString (WStringP, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum, MdlDesc *m=NULL)
	This version of mdlResource_loadWString allows the caller to pass a pointer to the output buffer, and the pointer may be NULL. More...
static RMGRSUBS_EXPORT StatusInt	AddByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, void *pRsc, size_t rscSize, WCharCP pAlias)
	This is used to add a new resource to a resource file. More...
static RMGRSUBS_EXPORT StatusInt	ChangeAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Allows an application assign a new alias name to a resource. More...
static RMGRSUBS_EXPORT StatusInt	CreateFileForPlatform (WCharCP pFilename, CharCP pIdent, UInt32 version, UInt32 platformId)
	This is used to generate a new resource file. More...
static RMGRSUBS_EXPORT StatusInt	DirectAdd (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias, RscDirectAccess *pDirect)
	Gives the MDL programmer full control of writing resources to a resource file. More...
static RMGRSUBS_EXPORT StatusInt	DirectAddComplete (void)
	Use this function to inform the resource manager that a new resource was added with RmgrResource::DirectAdd. More...
static RMGRSUBS_EXPORT StatusInt	GetRscIdByAlias (RscId *pRscId, RscFileHandle rfHandle, RscType typeId, WCharCP pAlias)
	Obtains a resource's identification number from its ASCII alias name. More...
static RMGRSUBS_EXPORT StatusInt	QueryFile (UInt32 *pReturnValue, WCharCP pFilename, long queryId)
	Queries the resource manager for information regarding a resource file. More...
static RMGRSUBS_EXPORT void *	Resize (void *pResource, size_t newSize)
	Adjusts the size of a resource in a file. More...
static RMGRSUBS_EXPORT StatusInt	Add (RscFileHandle rfHandle, RscType typeId, RscId rscId, void *pRsc, size_t rscSize, WCharCP pAlias)
	Used to add a new resource to a resource file. More...
static RMGRSUBS_EXPORT void	CloseFile (RscFileHandle rfHandle)
	Closes a resource file. More...
static RMGRSUBS_EXPORT StatusInt	CreateResourceFile (WCharCP pFilename, CharCP pIdent, UInt32 version)
	Used to generate a new resource file. More...
static RMGRSUBS_EXPORT StatusInt	Delete (RscFileHandle rfHandle, RscType typeId, RscId rscId)
	Deletes a resource with a given resource ID from a resource file. More...
static RMGRSUBS_EXPORT StatusInt	DeleteByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Deletes a resource with a given resource ID from a resource file. More...
static RMGRSUBS_EXPORT long	DirectLoad (RscFileHandle rfHandle, RscType typeId, RscId rscId, RscDirectAccess *pDirect)
	Allow the application control of resource loading. More...
static RMGRSUBS_EXPORT StatusInt	Free (void *pResource)
	Removes a resource from memory. More...
static RMGRSUBS_EXPORT void *	Load (RscFileHandle rfHandle, RscType typeId, RscId rscId)
	Used to load resources from an opened resource file. More...
static RMGRSUBS_EXPORT void *	LoadByAlias (RscFileHandle rfHandle, RscType typeId, RscId rscId, WCharCP pAlias)
	Used to load resources from an opened resource file. More...
static RMGRSUBS_EXPORT StatusInt	OpenFile (RscFileHandle *pRfHandle, WCharCP pFileName, UInt32 fileAttributes)
	Opens a resource file, making its contents available to the application using subsequent mdlResource_... More...
static RMGRSUBS_EXPORT StatusInt	Query (void *pReturnValue, void *pResource, long queryId)
	Queries the resource manager for information regarding a resource. More...
static RMGRSUBS_EXPORT StatusInt	QueryClass (void *pReturnValue, RscFileHandle rfHandle, RscType typeId, long queryId, void *pArg)
	Queries the resource manager for information regarding a resourceclass. More...
static RMGRSUBS_EXPORT StatusInt	QueryClassByAlias (void *pReturnValue, RscFileHandle rfHandle, RscType typeId, long queryId, void *pArg, WCharCP pAlias)
	Queries the resource manager for information regarding a resourceclass. More...
static RMGRSUBS_EXPORT StatusInt	Write (void *pResource)
	Writes an updated resource (obtained with RmgrResource::Load) to its original position in the resource file from which it was loaded. More...
static RMGRSUBS_EXPORT StatusInt	QueryFileHandle (void *pReturnValue, long retValSize, RscFileHandle rfHandle, long queryId, void *pArg)
	Queries the resource manager for information regarding an open resource file (or files). More...
static RMGRSUBS_EXPORT StatusInt	QueryFileName (WStringR fileName, RscFileHandle rfHandle)
	Queries the resource manager for the file name for an open resource file. More...
static RMGRSUBS_EXPORT StatusInt	LoadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc *mdlDesc=NULL)
	Copies the wide character string identified by listId and stringNum into the WString referenced by outString. More...

Detailed Description

This is used to add a new resource to a resource file.

Parameters

[in]	rfHandle	Is the resource file handle for the file where the new resource will be written. rfHandle is obtained from the mdlResource_openFile function.
[in]	typeId	Specifies the new resource's type or class.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pRsc	Points to a block of memory to be added to the file as a resource.
[in]	rscSize	Is the size of the block of memory pointed to by resource.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.

Remarks

The mdlResource_addByAlias function is identical to the mdlResource_add function except the combination of resourceID and alias are used to ensure uniqueness. Put another way, mdlResource_add will fail if either resourceID or alias is not unique within the resourceclass. But with mdlResource_addByAlias, the combination of resourceID and alias are checked as a pair.

If the file specified by rfHandle is version 5 (or later) resource file format, then the resource manager must be able to find a data definition corresponding to the resource type being added. This is still true even if the target resource file is optimized for the current platform. The resource manager will be successful in finding a data definition for the target resource if a corresponding data definition can be found in one of the following:

• The target resource file
• Another file currently open by the calling application, or
• A MicroStation system resource file

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file. In the case of mdlResource_addByAlias, resourceID and alias already exist as a pair on a resource.
MDLERR_RSCFILEERROR	Error encountered while reading the resource file header.
MDLERR_RSCWRITEERROR	Error encountered while writing to the file.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_DATADEFNOTFOUND	Could not find a data definition corresponding to the resourceclass.

See also

mdlResource_directAdd

Remarks

Required Library: mdlbltin.lib

Function Documentation

static RMGRSUBS_EXPORT StatusInt Add ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, void *  pRsc, size_t  rscSize, WCharCP  pAlias  )

static

Used to add a new resource to a resource file.

Parameters

[in]	rfHandle	Is the resource file handle for the file where the new resource will be written. rfHandle is obtained from the RmgrResource::OpenFile function.
[in]	typeId	Specifies the new resource's type or class.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pRsc	Points to a block of memory to be added to the fileas a resource.
[in]	rscSize	Is the size of the block of memory pointed to by resource.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.

Remarks

The RmgrResource::AddByAlias function is identical to the RmgrResource::Add function except the combination of resourceID and alias are used to ensure uniqueness. Put another way, RmgrResource::Add will fail if either resourceID or alias is not unique within the resourceclass. But with RmgrResource::AddByAlias, the combination of resourceID and alias are checked as a pair.

If the file specified by rfHandle is version 5 (or later) resource file format, then the resource manager must be able to find a data definition corresponding to the resource type being added. This is still true even if the target resource file is optimized for the current platform. The resource manager will be successful in finding a data definition for the target resource if a corresponding data definition can be found in one of the following:

• The target resource file
• Another file currently open by the calling application, or
• A MicroStation system resource file

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file. In the case of RmgrResource::AddByAlias, resourceID and alias already exist as a pair on a resource.
MDLERR_RSCFILEERROR	Error encountered while reading the resource file header.
MDLERR_RSCWRITEERROR	Error encountered while writing to the file.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_DATADEFNOTFOUND	Could not find a data definition corresponding to the resourceclass.

See also

RmgrResource::DirectAdd

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt AddByAlias ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, void *  pRsc, size_t  rscSize, WCharCP  pAlias  )

static

This is used to add a new resource to a resource file.

Parameters

[in]	rfHandle	Is the resource file handle for the file where the new resource will be written. rfHandle is obtained from the RmgrResource::OpenFile function.
[in]	typeId	Specifies the new resource's type or class.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pRsc	Points to a block of memory to be added to the file as a resource.
[in]	rscSize	Is the size of the block of memory pointed to by resource.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.

Remarks

The RmgrResource::AddByAlias function is identical to the RmgrResource::Add function except the combination of resourceID and alias are used to ensure uniqueness. Put another way, RmgrResource::Add will fail if either resourceID or alias is not unique within the resourceclass. But with RmgrResource::AddByAlias, the combination of resourceID and alias are checked as a pair.

If the file specified by rfHandle is version 5 (or later) resource file format, then the resource manager must be able to find a data definition corresponding to the resource type being added. This is still true even if the target resource file is optimized for the current platform. The resource manager will be successful in finding a data definition for the target resource if a corresponding data definition can be found in one of the following:

• The target resource file
• Another file currently open by the calling application, or
• A MicroStation system resource file

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file. In the case of RmgrResource::AddByAlias, resourceID and alias already exist as a pair on a resource.
MDLERR_RSCFILEERROR	Error encountered while reading the resource file header.
MDLERR_RSCWRITEERROR	Error encountered while writing to the file.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_DATADEFNOTFOUND	Could not find a data definition corresponding to the resourceclass.

See also

RmgrResource::DirectAdd

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt ChangeAlias ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, WCharCP  pAlias  )

static

Allows an application assign a new alias name to a resource.

Parameters

[in]	rfHandle	Is the resource file handle of the file containing the resource whose alias name will be changed. If rfHandle equals zero, the resource manager will check all resource files currently opened by the application.
[in]	typeId	Identifies the class of the resource whose alias name will be changed.
[in]	rscId	Identifies the resource whose alias name will be changed.
[in]	pAlias	Points to the new ASCII alias name to be assigned to the resource.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errorsdefined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCNOTFOUND	resourceID could not be found in the file(s).

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT void CloseFile ( RscFileHandle  rfHandle )

static

Closes a resource file.

All resources currently in memory that were loaded from the file beingclosed are automatically freed.

Remarks

Do not call RmgrResource::Free for a resource that has already been freed by virtue of a call to RmgrResource::CloseFile.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to the file to close. rfHandle is originally obtained from the RmgrResource::OpenFile function.

Returns

No return value.

See also

RmgrResource::OpenFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt CreateFileForPlatform ( WCharCP  pFilename, CharCP  pIdent, UInt32  version, UInt32  platformId  )

static

This is used to generate a new resource file.

The resulting file must be opened with RmgrResource::OpenFile before new resources may be added to it.

Parameters

[in]	pFilename	Is the name of the new resource file to be created.
[in]	pIdent	Is an identity string containing up to 63 characters that is stored in the new resource file header.
[in]	version	Is an application-defined 32-bit integer stored in the file header.

Remarks

The RmgrResource::CreateResourceFile function generates a resource file optimized for (i.e., in the format of) the current platform.

To create and optimize a resource file for a specific platform, the RmgrResource::CreateFileForPlatform function is called with the additional platformID parameter. The RmgrResource::CreateFileForPlatform function can also be used to generate a resource file that is compatible with version 4.x of MicroStation (for the current platform only).

Parameters

[in]

platformId

Identifier used to identify one of the platforms supported by MicroStation. The valid platform identifiers are defined in basedefs.h. Only PLATFORM_PC_WINNT should be used for V8 and later versions.

Returns

SUCCESS if the file was created. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILEERROR	An undefined error was encountered.
MDLERR_RSCINSFMEM	Memory is insufficient to create the file header.
MDLERR_INVALIDPLATFORMID	Invalid platform identifier.

See also

RmgrResource::OpenFile

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt CreateResourceFile ( WCharCP  pFilename, CharCP  pIdent, UInt32  version  )

static

Used to generate a new resource file.

The resulting file must be opened with RmgrResource::OpenFile before new resources may be added to it.

Parameters

[in]	pFilename	Is the name of the new resource file to be created.
[in]	pIdent	Is an identity string containing up to 63 characters that is stored in the new resource file header.
[in]	version	Is an application-defined 32-bit integer stored in the file header.

Remarks

This function generates a resource file optimized for (i.e., in the format of) the current platform.

To create and optimize a resource file for a specific platform, the RmgrResource::CreateFileForPlatform function is called with the additional platformID parameter. The RmgrResource::CreateFileForPlatform function can also be used to generate a resource file that is compatible with version 4.x of MicroStation (for the current platform only).

Returns

SUCCESS if the file was created. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILEERROR	An undefined error was encountered.
MDLERR_RSCINSFMEM	Memory is insufficient to create the file header.
MDLERR_INVALIDPLATFORMID	Invalid platform identifier.

See also

RmgrResource::OpenFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt Delete ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId  )

static

Deletes a resource with a given resource ID from a resource file.

The RmgrResourceMT::DeleteByAlias function deletes a resource with a given resource ID and alias name from a resource file. The calling application must have opened a file containing the resource using the RmgrResource::OpenFile function. If the target resource is currently loaded by any application (including the calling application), the request is rejected. In this case, the resource must be freed using RmgrResource::Free before a subsequent delete request can be honored.

Parameters

[in]	rfHandle	Is the resource file handle of the file wherethe resource will be deleted. rfHandle is obtained from the RmgrResource::OpenFile function. Passing zero for rfHandle is not allowed.
[in]	typeId	Identifies the type of resource being deleted.
[in]	rscId	Identifies the specific resource within the resourceclass to delete.

Returns

SUCCESS if the delete was successful. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCTYPEINVALID	Invalid resource type for the specified file.
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The specified resource is loaded and in use; it cannot be deleted.
MDLERR_RSCNOTFOUND	The specified resource could not be found in the resource file.

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt DeleteByAlias ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, WCharCP  pAlias  )

static

Deletes a resource with a given resource ID from a resource file.

The RmgrResourceMT::DeleteByAlias function deletes a resource with a given resource ID and alias name from a resource file. The calling application must have opened a file containing the resource using the RmgrResource::OpenFile function. If the target resource is currently loaded by any application (including the calling application), the request is rejected. In this case, the resource must be freed using RmgrResource::Free before a subsequent delete request can be honored.

Parameters

[in]	rfHandle	Is the resource file handle of the file where the resource will be deleted. rfHandle is obtained from the RmgrResource::OpenFile function. Passing zero for rfHandle is not allowed.
[in]	typeId	Identifies the type of resource being deleted.
[in]	rscId	Identifies the specific resource within the resourceclass to delete
[in]	pAlias	Only used with RmgrResourceMT::DeleteByAlias, is used along with resourceID to uniquely identify the resource to be deleted.

Returns

SUCCESS if the delete was successful. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCTYPEINVALID	Invalid resource type for the specified file.
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The specified resource is loaded and in use; it cannot be deleted.
MDLERR_RSCNOTFOUND	The specified resource could not be found in the resource file.

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt DirectAdd ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, WCharCP  pAlias, RscDirectAccess *  pDirect  )

static

Gives the MDL programmer full control of writing resources to a

resource file.

Another routine for adding new resources, RmgrResource::Add, requires the resource (memory area) to exist in its entirety at the time it is added to the file. After calling RmgrResource::DirectAdd, however, the programmer can write the new resource to the file piece by piece as necessary using the fwrite C function. The size of the resulting resource is equal to the sum of the sizes of the fwrites and is computed when the programmer calls RmgrResource::DirectAddComplete.

Remarks

Since the application assumes control for creating the resource, the resource manager cannot convert the resource from memory to file format (if necessary) as it does in the RmgrResource::Add function. It is the application's responsibility to check the parent resource file's format to see if the file format differs from the current platform's memory format. See RmgrResource::QueryFileHandle (queryID RSC_QRY_PLATFORM) for details.

The resource manager verifies that the specified resourceID and alias of the given resourceclass do not already exist in the file specified by rfHandle. If the proposed new resource is unique, the resource manager will return the information needed to write directly to the resource file in the structure pointed to by direct. The application then uses this information to write the resource to the file using one or more fwrite calls. When the application has completed its last fwrite call, it calls the RmgrResource::DirectAddComplete function to inform the resource manager that the new resource has been added. The resource manager then updates the resource file's header information to reflect the new resource addition.

No intervening resource management function calls should be made between the RmgrResource::DirectAdd and RmgrResource::DirectAddComplete. Furthermore, no other MDL application or MicroStation should be allowed to access the resource file where the resource is being added until after the RmgrResource::DirectAddComplete function call has been made. This means that the MDL application should make both function calls, RmgrResource::DirectAdd and RmgrResource::DirectAddComplete before returning to MicroStation. For example, the calls would not be made from separate event handlers.

Parameters

[in]	rfHandle	Is the resource file handle of the file where the new resource will be written. rfHandle is obtained from the RmgrResource::OpenFile function. This parameter must be specified. (Zero is invalid.)
[in]	typeId	Specifies the type or class of the new resource.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.
[out]	pDirect	Points to the following structure (defined in the MDL system header file mdlerrs.r.h) to be filled in by RmgrResource::DirectAdd: Value Description MDLERR_RSCWRITEVIOLATION The resource file was opened as RSC_READONLY. MDLERR_RSCALREADYEXISTS resourceID or alias already exists in the file. MDLERR_RSCFILE_ERROR The resource file header cannot be read. MDLERR_RSCINSFMEM Memory is insufficient to process the request. MDLERR_RSCERROR NULL pointer for direct is invalid. MDLERR_RSCDIRECTADDPEND A direct add is in progress.

Returns

SUCCESS if the application can safely begin writing the new resource to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file.
MDLERR_RSCFILE_ERROR	The resource file header cannot be read.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_RSCERROR	NULL pointer for direct is invalid.
MDLERR_RSCDIRECTADDPEND	A direct add is in progress.

See also

RmgrResource::DirectAddComplete RmgrResource::DirectLoad RmgrResource::Add

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt DirectAddComplete ( void  )

static

Use this function to inform the resource manager that a new resource was

added with RmgrResource::DirectAdd.

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	A direct add is not in progress.

See also

RmgrResource::DirectAdd

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT long DirectLoad ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, RscDirectAccess *  pDirect  )

static

Allow the application control of resource loading.

Remarks

Like RmgrResource::Load, its parameter list includes rfHandle, resourceclass, and resourceID. But, while RmgrResource::Load loads the resource in memory for the application, RmgrResource::DirectLoad obtains a pointer to a structure that contains a file pointer and the resource's size and position in the file. The MDL application can then load the resource using the standard fread function.

Since the application assumes control for loading the resource,the resource manager cannot convert the resource to memory format (if necessary) as it does in the RmgrResource::Load function. It is the application's responsibility to check the parent resource file's format to see if the file format differs from the current platform's memory format. See RmgrResource::QueryFileHandle (queryID RSC_QRY_PLATFORM) for details.

Sometimes RmgrResource::DirectLoad is preferred over RmgrResource::Load. For example, resource data loaded using RmgrResource::Load remains in memory only as long as the resource file remains open. A direct load, however, lets the application load a resource into the appropriate memory. Thus, the application does not need to keep the resource file open while accessing the resource data. A second reason for using a direct load concerns the size of resources. Since RmgrResource::Load obtains a resource in its entirety, memory could be wasted if only part of a very large resource was needed. RmgrResource::DirectLoad eliminates this problem by allowing the application to load in sections of a resource.

Parameters

[in]	rfHandle	Is the resource file handle corresponding to a file that was opened using the RmgrResource::OpenFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request as it does with RmgrResource::Load.
[in]	typeId	Identifies the type of resource being loaded
[in]	rscId	Specifies the resource to load.
[out]	pDirect	Information needed to access the resource directly

Remarks

pDirect points to the following structure (defined in the MDL system header file rscdefs.r.h) to be filled in by RmgrResource::DirectLoad:

typedef struct rscdirectaccess
{
   RscFileHandle rfHandle;   resource file handle
   FILE *fileP;              file ptr returned by fopen
   unsigned long filePos;    position of rsc. in the file
   unsigned long rscSize;    size of the resource
} RscDirectAccess;

The rfHandle structure member will not differ from rfHandle unless the function parameter was 0. In this case, rfHandle indicates the first file where the resource manager was able to find the target resource. Also, the fileP member is not guaranteed to be valid after the calling application has given up program control and another application (or MicroStation) has made a resource manager function call.

Returns

SUCCESS if the RscDirectAccess information was obtained. Otherwise, it returns one of these errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	The resource file could not be found.
MDLERR_RSCNOTFOUND	resourceID could not be found.

See also

RmgrResource::Load RmgrResource::DirectAdd RmgrResource::QueryFileHandle

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt Free ( void *  pResource )

static

Removes a resource from memory.

The resource must have been loaded with the RmgrResource::Load function.

Parameters

[in]

pResource

Points to a resource.

Remarks

Do not call RmgrResource::Free for a resource that has already been freed by a call to RmgrResource::CloseFile.

Returns

SUCCESS if the resource was removed successfully. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.

See also

RmgrResource::Load RmgrResource::CloseFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt GetRscIdByAlias ( RscId *  pRscId, RscFileHandle  rfHandle, RscType  typeId, WCharCP  pAlias  )

static

Obtains a resource's identification number from its ASCII alias name.

A resource's alias name can be a maximum of 16 characters and is assigned using the RmgrResource::Add, RmgrResource::DirectAdd or RmgrResource::ChangeAlias function.

Parameters

[out]	pRscId	Points to an unsigned long where the ID of the resource with the matching alias name will be stored.
[in]	rfHandle	Is the resource file handle of the file that will be checked for resourceclass and alias. If rfHandle equals zero, the resource manager will check all resource files currently opened by the application.
[in]	typeId	Identifies the resource class that will be searched to find alias.
[in]	pAlias	Points to the ASCII alias name associated with the resource whose identification number will be obtained. All resources of class resourceclass will be searched to find the matching alias. An alias name can be a maximum of 16 characters.

Returns

SUCCESS if the function was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	NULL is not a valid resourceID pointer.
MDLERR_RSCNOTFOUND	alias could not be found in the resource file(s).

See also

RmgrResource::ChangeAlias

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT void* Load ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId  )

static

Used to load resources from an opened resource file.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to a file that was previously opened with the RmgrResource::OpenFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request in one of two ways. First, it will search for the specified resource in all resource files currently opened by the calling application. If that search fails, it will attempt to find the resource in the system resource files currently opened by MicroStation. In either case, the files are searched in last opened, first searched sequence.

Remarks

If the file specified by rfHandle is optimized for a different platform from the current platform, the resource manager will automatically convert the resource to the current platform format. It does this by finding a data definition resource and then using it to convert the target resource to native machine format. The data definition resource can come from any file opened by the current application, even from a file optimized for a different file format than the target resource.

For example, let's say the current platform is the Macintosh, the target resource file is optimized for the PC, and a data definition corresponding to the target resource's resourceclass has been found in a Clipper format resource file. The data definition will be translated from describing Clipper format to describe PC format, then the target resource is loaded and translated from PC to Macintosh format.

Parameters

[in]	typeId	Identifies the class of the resource being loaded.
[in]	rscId	Specifies the resource to load.

Returns

A pointer to the loaded resource if the resource was found in the file. Otherwise, NULL is returned and mdlErrno will be set to one of the following error codes:

Value	Description
MDLERR_RSCFILENOTFOUND	An undefined error was encountered.
MDLERR_INSFMEMORY	Insufficient memory to load the resource.
MDLERR_RSCTYPEINVALID	Invalid resource type for the file specified.
MDLERR_RSCNOTFOUND	Cannot find the resource in the file specified.
MDLERR_RSCFILEERROR	An undefined error was encountered while trying to read the resource from file.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to memory format.

Remarks

The resource pointer returned by RmgrResource::Load or RmgrResource::LoadByAlias is valid only as long as the resource file from which it came stays open and the resource is not freed. Once a resourcefile is closed, all of its associated resources in memory are immediately released.

See also

RmgrResource::Free

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT void* LoadByAlias ( RscFileHandle  rfHandle, RscType  typeId, RscId  rscId, WCharCP  pAlias  )

static

Used to load resources from an opened resource file.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to a file that was previously opened with the RmgrResource::OpenFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request in one of two ways. First, it will search for the specified resource in all resource files currently opened by the calling application. If that search fails, it will attempt to find the resource in the system resource files currently opened by MicroStation. In either case, the files are searched in last opened, first searched sequence.

Remarks

If the file specified by rfHandle is optimized for a different platform from the current platform, the resource manager will automatically convert the resource to the current platform format. It does this by finding a data definition resource and then using it to convert the target resource to native machine format. The data definition resource can come from any file opened by the current application, even from a file optimized for a different file format than the target resource.

For example, let's say the current platform is the Macintosh, the target resource file is optimized for the PC, and a data definition corresponding to the target resource's resourceclass has been found in a Clipper format resource file. The data definition will be translated from describing Clipper format to describe PC format, then the target resource is loaded and translated from PC to Macintosh format.

Parameters

[in]	typeId	Identifies the class of the resource being loaded.
[in]	rscId	Specifies the resource to load.
[in]	pAlias	Alias of resource to load

Remarks

RmgrResource::LoadByAlias allows for an additional level of qualification by using the alias name of the resource. In this case, a resource with an ID of resourceID and an alias name of alias is located and loaded.

Returns

A pointer to the loaded resource if the resource was found in the file. Otherwise, NULL is returned and mdlErrno will be set to one of the following error codes:

Value	Description
MDLERR_RSCFILENOTFOUND	An undefined error was encountered.
MDLERR_INSFMEMORY	Insufficient memory to load the resource.
MDLERR_RSCTYPEINVALID	Invalid resource type for the file specified.
MDLERR_RSCNOTFOUND	Cannot find the resource in the file specified.
MDLERR_RSCFILEERROR	An undefined error was encountered while trying to read the resource from file.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to memory format.

Remarks

The resource pointer returned by RmgrResource::Load or RmgrResource::LoadByAlias is valid only as long as the resource file from which it came stays open and the resource is not freed. Once a resource file is closed, all of its associated resources in memory are immediately released.

See also

RmgrResource::Free

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt LoadWString ( WStringR  outString, RscFileHandle  rfHandle, UInt32  listId, UInt32  stringNum, MdlDesc *  mdlDesc = NULL  )

static

Copies the wide character string identified by listId and stringNum into the WString referenced by outString.

Remarks

listId must be the id of a MessageList (RTYPE_MESSAGES). RmgrResource::LoadWString looks for strings in MessageList resources. RmgrResource::LoadFromStringList also looks for strings in a similar fashion.

If necessary, the appropriate string list is loaded from the file indicated by rfHandle.

Parameters

[out]	outString	where the target string will be copied. If the function returns an error because the string could not be loaded, then outString is not set or cleared.
[in]	rfHandle	Is the resource file handle corresponding to a file that was opened using the RmgrResource::OpenFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request as it does in RmgrResource::Load.
[in]	listId	Is the resource ID of the string list containing the target string.
[in]	stringNum	Specifies the string to load.
[in]	mdlDesc	MdlDesc of the owning task of the resource

Returns

SUCCESS if the string was loaded. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	The resource file could not be found.
MDLERR_RSCNOTFOUND	stringListID could not be found.

See also

RmgrResource::LoadFromStringList

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

StatusInt mdlResource_add	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		void *	pRsc,
		size_t	rscSize,
		WCharCP	pAlias
	)

Used to add a new resource to a resource file.

Parameters

[in]	rfHandle	Is the resource file handle for the file where the new resource will be written. rfHandle is obtained from the mdlResource_openFile function.
[in]	typeId	Specifies the new resource's type or class.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pRsc	Points to a block of memory to be added to the fileas a resource.
[in]	rscSize	Is the size of the block of memory pointed to by resource.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.

Remarks

The mdlResource_addByAlias function is identical to the mdlResource_add function except the combination of resourceID and alias are used to ensure uniqueness. Put another way, mdlResource_add will fail if either resourceID or alias is not unique within the resourceclass. But with mdlResource_addByAlias, the combination of resourceID and alias are checked as a pair.

If the file specified by rfHandle is version 5 (or later) resource file format, then the resource manager must be able to find a data definition corresponding to the resource type being added. This is still true even if the target resource file is optimized for the current platform. The resource manager will be successful in finding a data definition for the target resource if a corresponding data definition can be found in one of the following:

• The target resource file
• Another file currently open by the calling application, or
• A MicroStation system resource file

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file. In the case of mdlResource_addByAlias, resourceID and alias already exist as a pair on a resource.
MDLERR_RSCFILEERROR	Error encountered while reading the resource file header.
MDLERR_RSCWRITEERROR	Error encountered while writing to the file.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_DATADEFNOTFOUND	Could not find a data definition corresponding to the resourceclass.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_directAdd

Remarks

SERIALIZED

StatusInt mdlResource_addByAlias	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		void *	pRsc,
		size_t	rscSize,
		WCharCP	pAlias
	)

StatusInt mdlResource_changeAlias	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		WCharCP	pAlias
	)

Allows an application assign a new alias name to a resource.

Parameters

[in]	rfHandle	Is the resource file handle of the file containing the resource whose alias name will be changed. If rfHandle equals zero, the resource manager will check all resource files currently opened by the application.
[in]	typeId	Identifies the class of the resource whose alias name will be changed.
[in]	rscId	Identifies the resource whose alias name will be changed.
[in]	pAlias	Points to the new ASCII alias name to be assigned to the resource.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errorsdefined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCNOTFOUND	resourceID could not be found in the file(s).

Remarks

Required Library: mdlbltin.lib

void mdlResource_closeFile

(

RscFileHandle

rfHandle

)

Closes a resource file.

All resources currently in memory that were loaded from the file beingclosed are automatically freed.

Remarks

Do not call mdlResource_free for a resource that has already been freed by virtue of a call to mdlResource_closeFile.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to the file to close. rfHandle is originally obtained from the mdlResource_openFile function.

Returns

No return value.

See also

mdlResource_openFile

Remarks

SERIALIZED

Required Library: mdlbltin.lib

StatusInt mdlResource_createFile	(	WCharCP	pFilename,
		CharCP	pIdent,
		UInt32	version
	)

Used to generate a new resource file.

The resulting file must be opened with mdlResource_openFile before new resources may be added to it.

Parameters

[in]	pFilename	Is the name of the new resource file to be created.
[in]	pIdent	Is an identity string containing up to 63 characters that is stored in the new resource file header.
[in]	version	Is an application-defined 32-bit integer stored in the file header.

Remarks

This function generates a resource file optimized for (i.e., in the format of) the current platform.

To create and optimize a resource file for a specific platform, the mdlResource_createFileForPlatform function is called with the additional platformID parameter. The mdlResource_createFileForPlatform function can also be used to generate a resource file that is compatible with version 4.x of MicroStation (for the current platform only).

Returns

SUCCESS if the file was created. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILEERROR	An undefined error was encountered.
MDLERR_RSCINSFMEM	Memory is insufficient to create the file header.
MDLERR_INVALIDPLATFORMID	Invalid platform identifier.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_openFile

Remarks

SERIALIZED

StatusInt mdlResource_createFileForPlatform	(	WCharCP	pFilename,
		CharCP	pIdent,
		UInt32	version,
		UInt32	platformId
	)

This is used to generate a new resource file.

The resulting file must be opened with mdlResource_openFile before new resources may be added to it.

Parameters

[in]	pFilename	Is the name of the new resource file to be created.
[in]	pIdent	Is an identity string containing up to 63 characters that is stored in the new resource file header.
[in]	version	Is an application-defined 32-bit integer stored in the file header.

Remarks

The mdlResource_createFile function generates a resource file optimized for (i.e., in the format of) the current platform.

To create and optimize a resource file for a specific platform, the mdlResource_createFileForPlatform function is called with the additional platformID parameter. The mdlResource_createFileForPlatform function can also be used to generate a resource file that is compatible with version 4.x of MicroStation (for the current platform only).

Parameters

[in]

platformId

Identifier used to identify one of the platforms supported by MicroStation. The valid platform identifiers are defined in basedefs.h. Only PLATFORM_PC_WINNT should be used for V8 and later versions.

Returns

SUCCESS if the file was created. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILEERROR	An undefined error was encountered.
MDLERR_RSCINSFMEM	Memory is insufficient to create the file header.
MDLERR_INVALIDPLATFORMID	Invalid platform identifier.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_openFile

StatusInt mdlResource_delete	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId
	)

Deletes a resource with a given resource ID from a resource file.

The mdlResource_deleteByAlias function deletes a resource with a given resource ID and alias name from a resource file. The calling application must have opened a file containing the resource using the mdlResource_openFile function. If the target resource is currently loaded by any application (including the calling application), the request is rejected. In this case, the resource must be freed using mdlResource_free before a subsequent delete request can be honored.

Parameters

[in]	rfHandle	Is the resource file handle of the file wherethe resource will be deleted. rfHandle is obtained from the mdlResource_openFile function. Passing zero for rfHandle is not allowed.
[in]	typeId	Identifies the type of resource being deleted.
[in]	rscId	Identifies the specific resource within the resourceclass to delete.

Returns

SUCCESS if the delete was successful. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCTYPEINVALID	Invalid resource type for the specified file.
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The specified resource is loaded and in use; it cannot be deleted.
MDLERR_RSCNOTFOUND	The specified resource could not be found in the resource file.

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_deleteByAlias	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		WCharCP	pAlias
	)

Deletes a resource with a given resource ID from a resource file.

The mdlResource_deleteByAlias function deletes a resource with a given resource ID and alias name from a resource file. The calling application must have opened a file containing the resource using the mdlResource_openFile function. If the target resource is currently loaded by any application (including the calling application), the request is rejected. In this case, the resource must be freed using mdlResource_free before a subsequent delete request can be honored.

Parameters

[in]	rfHandle	Is the resource file handle of the file where the resource will be deleted. rfHandle is obtained from the mdlResource_openFile function. Passing zero for rfHandle is not allowed.
[in]	typeId	Identifies the type of resource being deleted.
[in]	rscId	Identifies the specific resource within the resourceclass to delete
[in]	pAlias	Only used with mdlResource_deleteByAlias, is used along with resourceID to uniquely identify the resource to be deleted.

Returns

SUCCESS if the delete was successful. Otherwise, they return one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCTYPEINVALID	Invalid resource type for the specified file.
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The specified resource is loaded and in use; it cannot be deleted.
MDLERR_RSCNOTFOUND	The specified resource could not be found in the resource file.

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_directAdd	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		WCharCP	pAlias,
		RscDirectAccess *	pDirect
	)

Gives the MDL programmer full control of writing resources to a

resource file.

Another routine for adding new resources, mdlResource_add, requires the resource (memory area) to exist in its entirety at the time it is added to the file. After calling mdlResource_directAdd, however, the programmer can write the new resource to the file piece by piece as necessary using the fwrite C function. The size of the resulting resource is equal to the sum of the sizes of the fwrites and is computed when the programmer calls mdlResource_directAddComplete.

Remarks

Since the application assumes control for creating the resource, the resource manager cannot convert the resource from memory to file format (if necessary) as it does in the mdlResource_add function. It is the application's responsibility to check the parent resource file's format to see if the file format differs from the current platform's memory format. See mdlResource_queryFileHandle (queryID RSC_QRY_PLATFORM) for details.

The resource manager verifies that the specified resourceID and alias of the given resourceclass do not already exist in the file specified by rfHandle. If the proposed new resource is unique, the resource manager will return the information needed to write directly to the resource file in the structure pointed to by direct. The application then uses this information to write the resource to the file using one or more fwrite calls. When the application has completed its last fwrite call, it calls the mdlResource_directAddComplete function to inform the resource manager that the new resource has been added. The resource manager then updates the resource file's header information to reflect the new resource addition.

No intervening resource management function calls should be made between the mdlResource_directAdd and mdlResource_directAddComplete. Furthermore, no other MDL application or MicroStation should be allowed to access the resource file where the resource is being added until after the mdlResource_directAddComplete function call has been made. This means that the MDL application should make both function calls, mdlResource_directAdd and mdlResource_directAddComplete before returning to MicroStation. For example, the calls would not be made from separate event handlers.

Parameters

[in]	rfHandle	Is the resource file handle of the file where the new resource will be written. rfHandle is obtained from the mdlResource_openFile function. This parameter must be specified. (Zero is invalid.)
[in]	typeId	Specifies the type or class of the new resource.
[in]	rscId	Uniquely identifies a resource within its class. If a resource of the specified resourceclass and resourceID already exists, the request to add the new resource is rejected.
[in]	pAlias	Is the alias name of the new resource. If no name is needed, alias is NULL. If a resource of the specified resourceclass and alias already exists, the request to add the new resource is rejected.
[out]	pDirect	Points to the following structure (defined in the MDL system header file mdlerrs.r.h) to be filled in by mdlResource_directAdd: Value Description MDLERR_RSCWRITEVIOLATION The resource file was opened as RSC_READONLY. MDLERR_RSCALREADYEXISTS resourceID or alias already exists in the file. MDLERR_RSCFILE_ERROR The resource file header cannot be read. MDLERR_RSCINSFMEM Memory is insufficient to process the request. MDLERR_RSCERROR NULL pointer for direct is invalid. MDLERR_RSCDIRECTADDPEND A direct add is in progress.

Returns

SUCCESS if the application can safely begin writing the new resource to the resource file. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCALREADYEXISTS	resourceID or alias already exists in the file.
MDLERR_RSCFILE_ERROR	The resource file header cannot be read.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.
MDLERR_RSCERROR	NULL pointer for direct is invalid.
MDLERR_RSCDIRECTADDPEND	A direct add is in progress.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_directAddComplete mdlResource_directLoad mdlResource_add

StatusInt mdlResource_directAddComplete

(

)

Use this function to inform the resource manager that a new resource was

added with mdlResource_directAdd.

Returns

SUCCESS if the new resource was added to the resource file. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	A direct add is not in progress.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_directAdd

long mdlResource_directLoad	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		RscDirectAccess *	pDirect
	)

Allow the application control of resource loading.

Remarks

Like mdlResource_load, its parameter list includes rfHandle, resourceclass, and resourceID. But, while mdlResource_load loads the resource in memory for the application, mdlResource_directLoad obtains a pointer to a structure that contains a file pointer and the resource's size and position in the file. The MDL application can then load the resource using the standard fread function.

Since the application assumes control for loading the resource,the resource manager cannot convert the resource to memory format (if necessary) as it does in the mdlResource_load function. It is the application's responsibility to check the parent resource file's format to see if the file format differs from the current platform's memory format. See mdlResource_queryFileHandle (queryID RSC_QRY_PLATFORM) for details.

Sometimes mdlResource_directLoad is preferred over mdlResource_load. For example, resource data loaded using mdlResource_load remains in memory only as long as the resource file remains open. A direct load, however, lets the application load a resource into the appropriate memory. Thus, the application does not need to keep the resource file open while accessing the resource data. A second reason for using a direct load concerns the size of resources. Since mdlResource_load obtains a resource in its entirety, memory could be wasted if only part of a very large resource was needed. mdlResource_directLoad eliminates this problem by allowing the application to load in sections of a resource.

Parameters

[in]	rfHandle	Is the resource file handle corresponding to a file that was opened using the mdlResource_openFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request as it does with mdlResource_load.
[in]	typeId	Identifies the type of resource being loaded
[in]	rscId	Specifies the resource to load.
[out]	pDirect	Information needed to access the resource directly

Remarks

pDirect points to the following structure (defined in the MDL system header file rscdefs.r.h) to be filled in by mdlResource_directLoad:

typedef struct rscdirectaccess
{
   RscFileHandle rfHandle;   resource file handle
   FILE *fileP;              file ptr returned by fopen
   unsigned long filePos;    position of rsc. in the file
   unsigned long rscSize;    size of the resource
} RscDirectAccess;

The rfHandle structure member will not differ from rfHandle unless the function parameter was 0. In this case, rfHandle indicates the first file where the resource manager was able to find the target resource. Also, the fileP member is not guaranteed to be valid after the calling application has given up program control and another application (or MicroStation) has made a resource manager function call.

Returns

SUCCESS if the RscDirectAccess information was obtained. Otherwise, it returns one of these errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	The resource file could not be found.
MDLERR_RSCNOTFOUND	resourceID could not be found.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_load mdlResource_directAdd mdlResource_queryFileHandle

Remarks

SERIALIZED

StatusInt mdlResource_free

(

void *

pResource

)

Removes a resource from memory.

The resource must have been loaded with the mdlResource_load function.

Parameters

[in]

pResource

Points to a resource.

Remarks

Do not call mdlResource_free for a resource that has already been freed by a call to mdlResource_closeFile.

Returns

SUCCESS if the resource was removed successfully. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.

See also

mdlResource_load mdlResource_closeFile

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_getRscIdByAlias	(	RscId *	pRscId,
		RscFileHandle	rfHandle,
		RscType	typeId,
		WCharCP	pAlias
	)

Obtains a resource's identification number from its ASCII alias name.

A resource's alias name can be a maximum of 16 characters and is assigned using the mdlResource_add, mdlResource_directAdd or mdlResource_changeAlias function.

Parameters

[out]	pRscId	Points to an unsigned long where the ID of the resource with the matching alias name will be stored.
[in]	rfHandle	Is the resource file handle of the file that will be checked for resourceclass and alias. If rfHandle equals zero, the resource manager will check all resource files currently opened by the application.
[in]	typeId	Identifies the resource class that will be searched to find alias.
[in]	pAlias	Points to the ASCII alias name associated with the resource whose identification number will be obtained. All resources of class resourceclass will be searched to find the matching alias. An alias name can be a maximum of 16 characters.

Returns

SUCCESS if the function was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	NULL is not a valid resourceID pointer.
MDLERR_RSCNOTFOUND	alias could not be found in the resource file(s).

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_changeAlias

void* mdlResource_load	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId
	)

Used to load resources from an opened resource file.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to a file that was previously opened with the mdlResource_openFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request in one of two ways. First, it will search for the specified resource in all resource files currently opened by the calling application. If that search fails, it will attempt to find the resource in the system resource files currently opened by MicroStation. In either case, the files are searched in last opened, first searched sequence.

Remarks

If the file specified by rfHandle is optimized for a different platform from the current platform, the resource manager will automatically convert the resource to the current platform format. It does this by finding a data definition resource and then using it to convert the target resource to native machine format. The data definition resource can come from any file opened by the current application, even from a file optimized for a different file format than the target resource.

For example, let's say the current platform is the Macintosh, the target resource file is optimized for the PC, and a data definition corresponding to the target resource's resourceclass has been found in a Clipper format resource file. The data definition will be translated from describing Clipper format to describe PC format, then the target resource is loaded and translated from PC to Macintosh format.

Parameters

[in]	typeId	Identifies the class of the resource being loaded.
[in]	rscId	Specifies the resource to load.

Returns

A pointer to the loaded resource if the resource was found in the file. Otherwise, NULL is returned and mdlErrno will be set to one of the following error codes:

Value	Description
MDLERR_RSCFILENOTFOUND	An undefined error was encountered.
MDLERR_INSFMEMORY	Insufficient memory to load the resource.
MDLERR_RSCTYPEINVALID	Invalid resource type for the file specified.
MDLERR_RSCNOTFOUND	Cannot find the resource in the file specified.
MDLERR_RSCFILEERROR	An undefined error was encountered while trying to read the resource from file.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to memory format.

Remarks

The resource pointer returned by mdlResource_load or mdlResource_loadByAlias is valid only as long as the resource file from which it came stays open and the resource is not freed. Once a resourcefile is closed, all of its associated resources in memory are immediately released.

See also

mdlResource_free

Remarks

Required Library: mdlbltin.lib

SERIALIZED

void* mdlResource_loadByAlias	(	RscFileHandle	rfHandle,
		RscType	typeId,
		RscId	rscId,
		WCharCP	pAlias
	)

Used to load resources from an opened resource file.

Parameters

[in]

rfHandle

Is the resource file handle corresponding to a file that was previously opened with the mdlResource_openFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request in one of two ways. First, it will search for the specified resource in all resource files currently opened by the calling application. If that search fails, it will attempt to find the resource in the system resource files currently opened by MicroStation. In either case, the files are searched in last opened, first searched sequence.

Remarks

If the file specified by rfHandle is optimized for a different platform from the current platform, the resource manager will automatically convert the resource to the current platform format. It does this by finding a data definition resource and then using it to convert the target resource to native machine format. The data definition resource can come from any file opened by the current application, even from a file optimized for a different file format than the target resource.

For example, let's say the current platform is the Macintosh, the target resource file is optimized for the PC, and a data definition corresponding to the target resource's resourceclass has been found in a Clipper format resource file. The data definition will be translated from describing Clipper format to describe PC format, then the target resource is loaded and translated from PC to Macintosh format.

Parameters

[in]	typeId	Identifies the class of the resource being loaded.
[in]	rscId	Specifies the resource to load.
[in]	pAlias	Alias of resource to load

Remarks

mdlResource_loadByAlias allows for an additional level of qualification by using the alias name of the resource. In this case, a resource with an ID of resourceID and an alias name of alias is located and loaded.

Returns

A pointer to the loaded resource if the resource was found in the file. Otherwise, NULL is returned and mdlErrno will be set to one of the following error codes:

Value	Description
MDLERR_RSCFILENOTFOUND	An undefined error was encountered.
MDLERR_INSFMEMORY	Insufficient memory to load the resource.
MDLERR_RSCTYPEINVALID	Invalid resource type for the file specified.
MDLERR_RSCNOTFOUND	Cannot find the resource in the file specified.
MDLERR_RSCFILEERROR	An undefined error was encountered while trying to read the resource from file.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to memory format.

Remarks

The resource pointer returned by mdlResource_load or mdlResource_loadByAlias is valid only as long as the resource file from which it came stays open and the resource is not freed. Once a resource file is closed, all of its associated resources in memory are immediately released.

Required Library: mdlbltin.lib

See also

mdlResource_free

Remarks

SERIALIZED

END_EXTERN_C StatusInt mdlResource_loadWString	(	WStringR	outString,
		RscFileHandle	rfHandle,
		UInt32	listId,
		UInt32	stringNum,
		MdlDesc *	m = NULL
	)

Copies the wide character string identified by listId and stringNum into the WString referenced by outString.

Remarks

listId must be the id of a MessageList (RTYPE_MESSAGES). mdlResource_loadWString looks for strings in MessageList resources. mdlResource_loadFromStringList also looks for strings in a similar fashion.

If necessary, the appropriate string list is loaded from the file indicated by rfHandle.

Parameters

[out]	outString	where the target string will be copied. If the function returns an error because the string could not be loaded, then outString is not set or cleared.
[in]	rfHandle	Is the resource file handle corresponding to a file that was opened using the mdlResource_openFile function. If rfHandle equals zero, the resource manager will attempt to satisfy the request as it does in mdlResource_load.
[in]	listId	Is the resource ID of the string list containing the target string.
[in]	stringNum	Specifies the string to load.
[in]	m	Client application.

Returns

SUCCESS if the string was loaded. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	The resource file could not be found.
MDLERR_RSCNOTFOUND	stringListID could not be found.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_loadFromStringList

Remarks

SERIALIZED

StatusInt mdlResource_loadWString	(	WStringP	,
		RscFileHandle	rfHandle,
		UInt32	listId2,
		UInt32	stringNum,
		MdlDesc *	m = NULL
	)

This version of mdlResource_loadWString allows the caller to pass a pointer to the output buffer, and the pointer may be NULL.

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_openFile	(	RscFileHandle *	pRfHandle,
		WCharCP	pFileName,
		UInt32	fileAttributes
	)

Opens a resource file, making its contents available to the application using subsequent mdlResource_...

function calls.

Remarks

The resource manager stores the resource file handle corresponding to the successfully opened file in rfHandle. The resource file handle is a parameter needed for most mdlResource_... functions.

Parameters

[out]	pRfHandle	Return resource file handle
[in]	pFileName	Specifies the target file to be opened. If the resource manager cannot find the file specified by fileName, it will search for the file in the path specified by the MS_RSRCPATH environment variable. If fileName is NULL, the resource manager will default to the calling application's original load file.
[in]	fileAttributes	Specifies file attributes to be assigned to the file such as the read/write capability. Each file attribute is specified as a bit mask. Several may be logically ORed together if more than one file attribute needs to be assigned. The valid file attribute masks, defined in rscdefs.r.h, are: Mask value Description RSC_READ Open file for read access, allow other readers. RSC_READDENYWRITE Open file for read access, deny writers. RSC_READWRITE Open file with read/write access.

Remarks

Do not confuse the MS_RSRCPATH environment variable with the MS_RSRC environment variable used to specify the location for the MicroStation resource file, ustation.rsc.

Returns

SUCCESS if the file was opened successfully. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	fileName could not be found.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_createFile mdlResource_closeFile

Remarks

SERIALIZED

StatusInt mdlResource_query	(	void *	pReturnValue,
		void *	pResource,
		long	queryId
	)

Queries the resource manager for information regarding a resource.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the query.
[in]	pResource	Points to a resource loaded with the mdlResource_load function.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_SIZE "What is the size of the resource as it appears in memory?" reply must point to an unsigned long. RSC_QRY_FILESIZE "What is the size of the resource as it appears in its parent file?" reply must point to an unsigned long. RSC_QRY_TYPE "What is the resourceclass of the resource?" reply must point to an unsigned long. RSC_QRY_ID "What is the resource ID of the resource?" reply must point to an unsigned long. RSC_QRY_FILEHANDLE "What is the handle of the resource's parent file?" reply must point to a variable of type RscFileHandle. RSC_QRY_ALIAS "What is the alias name of the resource?" reply must point to a WString that is filled with the alias. RSC_QRY_PLATFORM "What is the format (platform ID) of the resource's parent file?" reply must point to an integer.

Returns

The mdlResource_query function returns SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_queryClass mdlResource_queryFileHandle mdlResource_queryFile

Remarks

SERIALIZED

StatusInt mdlResource_queryClass	(	void *	pReturnValue,
		RscFileHandle	rfHandle,
		RscType	typeId,
		long	queryId,
		void *	pArg
	)

Queries the resource manager for information regarding a resourceclass.

The mdlResource_queryClassByAlias function has the same purpose except it allows the caller to limit the scope of the query to only reflect resources with a specific alias name, and it only honors the RSC_QRY_COUNT and RSC_QRY_ID query types.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	rfHandle	Is the resource file handle of the file containing the resourceclass being queried. rfHandle is obtained from the mdlResource_openFile function. If rfHandle equals zero, all resource files currently opened by the application are checked.
[in]	typeId	Identifies the type of resource being queried.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_COUNT Store the number of resources of this class in the integer pointed to by reply. RSC_QRY_ID Store the resourceID of the nth resource of the resourceclass ("n" is provided by *optarg) in the unsigned long variable pointed to by reply. For example, if optarg equals 5, the application is asking to receive the resourceID of the class's fifth resource. optarg is zero-based. RSC_QRY_ID_IN_USE Set reply to true if the resource ID pointed to by optarg is currently in use in the resourceclass. Otherwise set reply to false. RSC_QRY_ID_HIGHEST Store the highest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ID_LOWEST Store the lowest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ALIAS Same as RSC_QRY_ID, but the aliasname is returned instead of the resourceID. RSC_QRY_AVAIL_ID Store the next unused resourceID of the resourceclass (greater than or equal to zero) in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_ABOVE Store the next unused resourceID of the resourceclass, greater than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_BELOW Store the next unused resourceID of the resourceclass, less than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_FILEHANDLE After locating the nth resource of the resourceclass (where "n" is a zero-based index pointed to by optarg), store the RscFileHandle of the file where the resource was found at the location pointed to by reply.
[in]	pArg	Points to an optional argument whose value depends on the specific queryID as described above.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	An undefined error was encountered.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

mdlResource_query mdlResource_queryFileHandle mdlResource_queryFile

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_queryClassByAlias	(	void *	pReturnValue,
		RscFileHandle	rfHandle,
		RscType	typeId,
		long	queryId,
		void *	pArg,
		WCharCP	pAlias
	)

Queries the resource manager for information regarding a resourceclass.

This function has the same purpose except it allows the caller to limit the scope of the query to only reflect resources with a specific alias name, and it only honors the RSC_QRY_COUNT and RSC_QRY_ID query types.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	rfHandle	Is the resource file handle of the file containing the resourceclass being queried. rfHandle is obtained from the mdlResource_openFile function. If rfHandle equals zero, all resource files currently opened by the application are checked.
[in]	typeId	Identifies the type of resource being queried.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value <Description RSC_QRY_COUNT Store the number of resources of this class in the integer pointed to by reply. RSC_QRY_ID Store the resourceID of the nth resource of the resourceclass ("n" is provided by *optarg) in the unsigned long variable pointed to by reply. For example, if optarg equals 5, the application is asking to receive the resourceID of the class's fifth resource. optarg is zero-based. RSC_QRY_ID_IN_USE Set reply to true if the resource ID pointed to by optarg is currently in use in the resourceclass. Otherwise set reply to false. RSC_QRY_ID_HIGHEST Store the highest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ID_LOWEST Store the lowest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ALIAS Same as RSC_QRY_ID, but the aliasname is returned instead of the resourceID (256 character max). RSC_QRY_AVAIL_ID Store the next unused resourceID of the resourceclass (greater than or equal to zero) in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_ABOVE Store the next unused resourceID of the resourceclass, greater than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_BELOW Store the next unused resourceID of the resourceclass, less than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_FILEHANDLE After locating the nth resource of the resourceclass (where "n" is a zero-based index pointed to by optarg), store the RscFileHandle of the file where the resource was found at the location pointed to by reply.
[in]	pArg	Points to an optional argument whose value depends on the specific queryID as described above.
[in]	pAlias	Only consider rscs with this alias.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	<Description
MDLERR_RSCERROR	An undefined error was encountered.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

mdlResource_query mdlResource_queryFileHandle mdlResource_queryFile

Remarks

Required Library: mdlbltin.lib

SERIALIZED

StatusInt mdlResource_queryFile	(	UInt32 *	pReturnValue,
		WCharCP	pFilename,
		long	queryId
	)

Queries the resource manager for information regarding a resource file.

The resource manager will call mdlResource_openFile in order to gain access to the information. Afterwards, the file will be closed.

Remarks

If the file to be queried is already open, use the mdlResource_queryFileHandle function to avoid the overhead incurred calling this function.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	pFilename	Points to a NULL-terminated ASCII filename.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_NUMTYPES Store the number of resourceclasses in the file in the unsigned long variable pointed to by reply. RSC_QRY_CLASS Store a list of the resourceclasses in the file in reply. reply points to an array of unsigned long values allocated by the caller. The caller can determine the number of elements to malloc in the array by calling this function with queryID equal to RSC_QRY_NUMTYPES. RSC_QRY_VERSION Store the version of the resource file in reply. RSC_QRY_IDENT Copy the ident string of the resource file to the character array pointed to by reply.

Returns

mdlResource_queryFile returns SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCINSFMEM	Memory is insufficient to read the file's header.
MDLERR_RSCFILEERROR	The resource file cannot be read.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_queryFileHandle mdlResource_query mdlResource_querylassC

StatusInt mdlResource_queryFileHandle	(	void *	pReturnValue,
		long	retValSize,
		RscFileHandle	rfHandle,
		long	queryId,
		void *	pArg
	)

Queries the resource manager for information regarding an open resource file (or files).

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	retValSize	Indicates the size of the area pointed to by reply (in bytes).
[in]	rfHandle	Is a handle to the open resource file to be queried. rfHandle is ignored if queryID equals RSC_QRY_COUNT or RSC_QRY_FILEHANDLE.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_NUMTYPES Store the number of resourceclasses in the file in the unsigned long variable pointed to by reply. RSC_QRY_CLASS Store a list of the resourceclasses in the file in reply. reply points to an array of unsigned long values allocated by the caller. The caller can determine the number of elements to malloc in the array by calling this function with queryID equal to RSC_QRY_NUMTYPES. RSC_QRY_VERSION Store the version of the resource file in reply. RSC_QRY_IDENT Copy the ident string of the resource file to the character array pointed to by reply. RSC_QRY_FILEATTRS Store the file attribute mask for the file (as it was specified to the mdlResource_openFile function) in the 32-bit storage location pointed to by reply. RSC_QRY_PLATFORM Store the platformID of the open file in the unsigned long variable pointed to by reply. RSC_QRY_OWNER Store the MDL descriptor pointer of the task that originally opened the resource file in the 32-bit storage location pointed to by reply. RSC_QRY_COUNT Return the number of resource file handles owned by an application in the integer pointed to by reply. The number returned will also include files inherited from MicroStation. The target application's MDL descriptor is provided in optArg. If optArg is NULL, the number of handles owned by MicroStation is returned. RSC_QRY_FILEHANDLE Store all the resource file handles owned by an application in the array of resource file handles pointed to by reply. The number of handles returned will be dictated by the replysize argument. replySize should equal (number of handles * sizeof(RscFileHandle)). The target application's MDL descriptor is provided in optArg. If optArg is NULL, the handles owned by MicroStation are returned. To get the number of handles owned by the target task, call this function with a queryID of RSC_QRY_COUNT.
[in]	pArg	Is only used when queryID equals RSC_QRY_COUNT or RSC_QRY_FILEHANDLE. In these cases, optArg is the MDL descriptor of the task whose open files are being queried. Use the functions mdlSystem_findMdlDesc or mdlSystem_getCurrMdlDesc to obtain the MDL descriptor for a given task.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCINSFMEM	Memory is insufficient to read the file's header.
MDLERR_RSCFILEERROR	The resource file cannot be read.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_queryFile mdlResource_query mdlResource_querylassC mdlSystem_findMdlDesc mdlSystem_getCurrMdlDesc

Remarks

SERIALIZED

void* mdlResource_resize	(	void *	pResource,
		size_t	newSize
	)

Adjusts the size of a resource in a file.

No application except the calling application can load the resource. If newSize is larger than the previous size of the resource, the existing resource is padded with zero bytes until its size reaches newSize bytes. On the other hand, if newSize is smaller than the original size of the resource, bytes in the resource above newSize are truncated. If the attempt to resize the resource is successful, a pointer to the newly allocated resource is returned and the previous pointer is no longer valid.

Parameters

[in]	pResource	Points to a resource that was obtained in memory through the mdlResource_load function.
[in]	newSize	Is the new size to be assigned to the resource.

Returns

A pointer to the resized resource. If an error occurs, NULL is returned and the global variable mdlErrno is set to the specific cause of the error. The following are possible values for mdlErrno:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The resource is being used by more than one application.
MDLERR_RSCADDRINVALID	The resource pointer is invalid.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlResource_write

(

void *

pResource

)

Writes an updated resource (obtained with mdlResource_load) to its original position in the resource file from which it was loaded.

The size of the write is determined by the size of the resource.

Parameters

[in]

pResource

Points to a resource obtained in memory through mdlResource_load.

Returns

SUCCESS if the write was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.
MDLERR_RSCFILEERROR	An unrecoverable file error occurred.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to file format.

Remarks

Required Library: mdlbltin.lib

See also

mdlResource_load

Remarks

SERIALIZED

static RMGRSUBS_EXPORT StatusInt OpenFile ( RscFileHandle *  pRfHandle, WCharCP  pFileName, UInt32  fileAttributes  )

static

Opens a resource file, making its contents available to the application using subsequent mdlResource_...

function calls.

Remarks

The resource manager stores the resource file handle corresponding to the successfully opened file in rfHandle. The resource file handle is a parameter needed for most mdlResource_... functions.

Parameters

[out]	pRfHandle	Return resource file handle
[in]	pFileName	Specifies the target file to be opened. If the resource manager cannot find the file specified by fileName, it will search for the file in the path specified by the MS_RSRCPATH environment variable. If fileName is NULL, the resource manager will default to the calling application's original load file.
[in]	fileAttributes	Specifies file attributes to be assigned to the file such as the read/write capability. Each file attribute is specified as a bit mask. Several may be logically ORed together if more than one file attribute needs to be assigned. The valid file attribute masks, defined in rscdefs.r.h, are: Mask value Description RSC_READ Open file for read access, allow other readers. RSC_READDENYWRITE Open file for read access, deny writers. RSC_READWRITE Open file with read/write access.

Remarks

Do not confuse the MS_RSRCPATH environment variable with the MS_RSRC environment variable used to specify the location for the MicroStation resource file, ustation.rsc.

Returns

SUCCESS if the file was opened successfully. Otherwise, it returns the following error defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCFILENOTFOUND	fileName could not be found.

See also

RmgrResource::CreateResourceFile RmgrResource::CloseFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt Query ( void *  pReturnValue, void *  pResource, long  queryId  )

static

Queries the resource manager for information regarding a resource.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the query.
[in]	pResource	Points to a resource loaded with the RmgrResource::Load function.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_SIZE "What is the size of the resource as it appears in memory?" reply must point to an unsigned long. RSC_QRY_FILESIZE "What is the size of the resource as it appears in its parent file?" reply must point to an unsigned long. RSC_QRY_TYPE "What is the resourceclass of the resource?" reply must point to an unsigned long. RSC_QRY_ID "What is the resource ID of the resource?" reply must point to an unsigned long. RSC_QRY_FILEHANDLE "What is the handle of the resource's parent file?" reply must point to a variable of type RscFileHandle. RSC_QRY_ALIAS "What is the alias name of the resource?" reply must point to a WString that is filled with the alias. RSC_QRY_PLATFORM "What is the format (platform ID) of the resource's parent file?" reply must point to an integer.

Returns

The RmgrResource::Query function returns SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

RmgrResource::QueryClass RmgrResource::QueryFileHandle RmgrResource::QueryFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt QueryClass ( void *  pReturnValue, RscFileHandle  rfHandle, RscType  typeId, long  queryId, void *  pArg  )

static

Queries the resource manager for information regarding a resourceclass.

The RmgrResource::QueryClassByAlias function has the same purpose except it allows the caller to limit the scope of the query to only reflect resources with a specific alias name, and it only honors the RSC_QRY_COUNT and RSC_QRY_ID query types.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	rfHandle	Is the resource file handle of the file containing the resourceclass being queried. rfHandle is obtained from the RmgrResource::OpenFile function. If rfHandle equals zero, all resource files currently opened by the application are checked.
[in]	typeId	Identifies the type of resource being queried.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_COUNT Store the number of resources of this class in the integer pointed to by reply. RSC_QRY_ID Store the resourceID of the nth resource of the resourceclass ("n" is provided by *optarg) in the unsigned long variable pointed to by reply. For example, if optarg equals 5, the application is asking to receive the resourceID of the class's fifth resource. optarg is zero-based. RSC_QRY_ID_IN_USE Set reply to true if the resource ID pointed to by optarg is currently in use in the resourceclass. Otherwise set reply to false. RSC_QRY_ID_HIGHEST Store the highest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ID_LOWEST Store the lowest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ALIAS Same as RSC_QRY_ID, but the aliasname is returned instead of the resourceID. RSC_QRY_AVAIL_ID Store the next unused resourceID of the resourceclass (greater than or equal to zero) in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_ABOVE Store the next unused resourceID of the resourceclass, greater than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_BELOW Store the next unused resourceID of the resourceclass, less than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_FILEHANDLE After locating the nth resource of the resourceclass (where "n" is a zero-based index pointed to by optarg), store the RscFileHandle of the file where the resource was found at the location pointed to by reply.
[in]	pArg	Points to an optional argument whose value depends on the specific queryID as described above.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCERROR	An undefined error was encountered.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

RmgrResource::Query RmgrResource::QueryFileHandle RmgrResource::QueryFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt QueryClassByAlias ( void *  pReturnValue, RscFileHandle  rfHandle, RscType  typeId, long  queryId, void *  pArg, WCharCP  pAlias  )

static

Queries the resource manager for information regarding a resourceclass.

This function has the same purpose except it allows the caller to limit the scope of the query to only reflect resources with a specific alias name, and it only honors the RSC_QRY_COUNT and RSC_QRY_ID query types.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	rfHandle	Is the resource file handle of the file containing the resourceclass being queried. rfHandle is obtained from the RmgrResource::OpenFile function. If rfHandle equals zero, all resource files currently opened by the application are checked.
[in]	typeId	Identifies the type of resource being queried.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value <Description RSC_QRY_COUNT Store the number of resources of this class in the integer pointed to by reply. RSC_QRY_ID Store the resourceID of the nth resource of the resourceclass ("n" is provided by *optarg) in the unsigned long variable pointed to by reply. For example, if optarg equals 5, the application is asking to receive the resourceID of the class's fifth resource. optarg is zero-based. RSC_QRY_ID_IN_USE Set reply to true if the resource ID pointed to by optarg is currently in use in the resourceclass. Otherwise set reply to false. RSC_QRY_ID_HIGHEST Store the highest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ID_LOWEST Store the lowest in-use resourceID of the resourceclass in the unsigned long variable pointed to by reply. RSC_QRY_ALIAS Same as RSC_QRY_ID, but the aliasname is returned instead of the resourceID. RSC_QRY_AVAIL_ID Store the next unused resourceID of the resourceclass (greater than or equal to zero) in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_ABOVE Store the next unused resourceID of the resourceclass, greater than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_AVAIL_ID_BELOW Store the next unused resourceID of the resourceclass, less than optarg, in the unsigned long variable pointed to by reply. RSC_QRY_FILEHANDLE After locating the nth resource of the resourceclass (where "n" is a zero-based index pointed to by optarg), store the RscFileHandle of the file where the resource was found at the location pointed to by reply.
[in]	pArg	Points to an optional argument whose value depends on the specific queryID as described above.
[in]	pAlias	Only consider rscs with this alias.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	<Description
MDLERR_RSCERROR	An undefined error was encountered.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

RmgrResource::Query RmgrResource::QueryFileHandle RmgrResource::QueryFile

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt QueryFile ( UInt32 *  pReturnValue, WCharCP  pFilename, long  queryId  )

static

Queries the resource manager for information regarding a resource file.

The resource manager will call RmgrResource::OpenFile in order to gain access to the information. Afterwards, the file will be closed.

Remarks

If the file to be queried is already open, use the RmgrResource::QueryFileHandle function to avoid the overhead incurred calling this function.

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	pFilename	Points to a NULL-terminated ASCII filename.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_NUMTYPES Store the number of resourceclasses in the file in the unsigned long variable pointed to by reply. RSC_QRY_CLASS Store a list of the resourceclasses in the file in reply. reply points to an array of unsigned long values allocated by the caller. The caller can determine the number of elements to malloc in the array by calling this function with queryID equal to RSC_QRY_NUMTYPES. RSC_QRY_VERSION Store the version of the resource file in reply. RSC_QRY_IDENT Copy the ident string of the resource file to the character array pointed to by reply.

Returns

RmgrResource::QueryFile returns SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCINSFMEM	Memory is insufficient to read the file's header.
MDLERR_RSCFILEERROR	The resource file cannot be read.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

RmgrResource::QueryFileHandle RmgrResource::Query RmgrResource::QuerylassC

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt QueryFileHandle ( void *  pReturnValue, long  retValSize, RscFileHandle  rfHandle, long  queryId, void *  pArg  )

static

Queries the resource manager for information regarding an open resource file (or files).

Parameters

[out]	pReturnValue	Points to the location where the resource manager must place its answer to the request. The type of data that it points to depends on the type of the query.
[in]	retValSize	Indicates the size of the area pointed to by reply (in bytes).
[in]	rfHandle	Is a handle to the open resource file to be queried. rfHandle is ignored if queryID equals RSC_QRY_COUNT or RSC_QRY_FILEHANDLE.
[in]	queryId	Identifies the specific query request type. Valid request types are as follows: Value Description RSC_QRY_NUMTYPES Store the number of resourceclasses in the file in the unsigned long variable pointed to by reply. RSC_QRY_CLASS Store a list of the resourceclasses in the file in reply. reply points to an array of unsigned long values allocated by the caller. The caller can determine the number of elements to malloc in the array by calling this function with queryID equal to RSC_QRY_NUMTYPES. RSC_QRY_VERSION Store the version of the resource file in reply. RSC_QRY_IDENT Copy the ident string of the resource file to the character array pointed to by reply. RSC_QRY_FILEATTRS Store the file attribute mask for the file (as it was specified to the RmgrResource::OpenFile function) in the 32-bit storage location pointed to by reply. RSC_QRY_PLATFORM Store the platformID of the open file in the unsigned long variable pointed to by reply. RSC_QRY_OWNER Store the MDL descriptor pointer of the task that originally opened the resource file in the 32-bit storage location pointed to by reply. RSC_QRY_COUNT Return the number of resource file handles owned by an application in the integer pointed to by reply. The number returned will also include files inherited from MicroStation. The target application's MDL descriptor is provided in optArg. If optArg is NULL, the number of handles owned by MicroStation is returned. RSC_QRY_FILEHANDLE Store all the resource file handles owned by an application in the array of resource file handles pointed to by reply. The number of handles returned will be dictated by the replysize argument. replySize should equal (number of handles * sizeof(RscFileHandle)). The target application's MDL descriptor is provided in optArg. If optArg is NULL, the handles owned by MicroStation are returned. To get the number of handles owned by the target task, call this function with a queryID of RSC_QRY_COUNT.
[in]	pArg	Is only used when queryID equals RSC_QRY_COUNT or RSC_QRY_FILEHANDLE. In these cases, optArg is the MDL descriptor of the task whose open files are being queried. Use the functions mdlSystem_findMdlDesc or mdlSystem_getCurrMdlDesc to obtain the MDL descriptor for a given task.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCINSFMEM	Memory is insufficient to read the file's header.
MDLERR_RSCFILEERROR	The resource file cannot be read.
MDLERR_RSCQRYIDINVALID	queryID is invalid.

See also

RmgrResource::QueryFile RmgrResource::Query RmgrResource::QuerylassC mdlSystem_findMdlDesc mdlSystem_getCurrMdlDesc

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt QueryFileName ( WStringR  fileName, RscFileHandle  rfHandle  )

static

Queries the resource manager for the file name for an open resource file.

Parameters

[out]	fileName	The name of the resource file.
[in]	rfHandle	A handle to the resource to query.

Returns

SUCCESS if the query was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCINSFMEM	Memory is insufficient to read the file's header.
MDLERR_RSCFILEERROR	The resource file cannot be read.

See also

RmgrResource::QueryFile RmgrResource::Query RmgrResource::QuerylassC mdlSystem_findMdlDesc mdlSystem_getCurrMdlDesc

+------------—+------------—+------------—+------------—+------------—+---—

static RMGRSUBS_EXPORT void* Resize ( void *  pResource, size_t  newSize  )

static

Adjusts the size of a resource in a file.

No application except the calling application can load the resource. If newSize is larger than the previous size of the resource, the existing resource is padded with zero bytes until its size reaches newSize bytes. On the other hand, if newSize is smaller than the original size of the resource, bytes in the resource above newSize are truncated. If the attempt to resize the resource is successful, a pointer to the newly allocated resource is returned and the previous pointer is no longer valid.

Parameters

[in]	pResource	Points to a resource that was obtained in memory through the RmgrResource::Load function.
[in]	newSize	Is the new size to be assigned to the resource.

Returns

A pointer to the resized resource. If an error occurs, NULL is returned and the global variable mdlErrno is set to the specific cause of the error. The following are possible values for mdlErrno:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCINUSE	The resource is being used by more than one application.
MDLERR_RSCADDRINVALID	The resource pointer is invalid.
MDLERR_RSCINSFMEM	Memory is insufficient to process the request.

Remarks

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib

static RMGRSUBS_EXPORT StatusInt Write ( void *  pResource )

static

Writes an updated resource (obtained with RmgrResource::Load) to its original position in the resource file from which it was loaded.

The size of the write is determined by the size of the resource.

Parameters

[in]

pResource

Points to a resource obtained in memory through RmgrResource::Load.

Returns

SUCCESS if the write was successful. Otherwise, it returns one of the following errors defined in mdlerrs.r.h:

Value	Description
MDLERR_RSCWRITEVIOLATION	The resource file was opened as RSC_READONLY.
MDLERR_RSCADDRINVALID	resource is an invalid resource pointer.
MDLERR_RSCFILEERROR	An unrecoverable file error occurred.
MDLERR_DATADEFNOTFOUND	Could not find a data definition with which to convert the resource to file format.

See also

RmgrResource::Load

Remarks

SERIALIZED

Required library : RmgrTools<ApiNumber>.lib i.e. RmgrTools3.lib