Symbian
Developer Library

DEVELOPER LIBRARY

[Index] [Glossary] [Previous] [Next]

 » Developer Library » API Reference » C++ API reference » Dynamically Loading Link Libraries » RLibrary

Location: e32std.h
Link against: euser.lib

Class RLibrary

RLibrary

Support

Supported from 5.0

Description

Provides a handle to a dynamically loadable DLL.

The class is not intended for user derivation.

Derivation

RHandleBaseA handle to an object
RLibraryProvides a handle to a dynamically loadable DLL

Defined in RLibrary:
Close(), DllRefTable(), EntryPoint(), FileName(), GetRamSizes(), LibraryCallList(), Load(), Load(), Load(), Lookup(), Type()

Inherited from RHandleBase:
Duplicate(), Handle(), SetHandle()

Loading DLLs

Load()

TInt Load(const TDesC& aFileName,const TUidType& aType);

Description

Loads the named DLL which matches the specified UID type. If successful, the function increments the usage count by one.

No additional search paths can be specified with this function.

Parameters

const TDesC& aFileName

A descriptor containing the name of the DLL to be loaded. The length of the file name must not be greater than KMaxFileName.

const TUidType& aType

A UID type (a triplet of UIDs) which the DLL must match. Individual UIDs can contain the KNullUid wild card.

Return value

TInt

KErrNone, if successful KErrBadName, if the length of aFileName is greater than KMaxFileName otherwise one of the system wide error codes

Load()

TInt Load(const TDesC& aFileName,const TDesC& aPath,const TUidType& aType);

Description

Loads the named DLL which matches the specified UID type. If successful, the function increments the usage count by one.

Parameters

const TDesC& aFileName

A descriptor containing the name of the DLL to be loaded. The length of the file name must not be greater than KMaxFileName.

const TDesC& aPath

A descriptor containing a list of path names, each separated by a semicolon. These paths are searched for the DLL before the standard search locations.

const TUidType& aType

A UID type (a triplet of UIDs) which the DLL must match. Individual UIDs can contain the KNullUid wild card.

Return value

TInt

KErrNone, if successful KErrBadName, if the length of aFileName is greater than KMaxFileName otherwise one of the system wide error codes

Load()

TInt Load(const TDesC& aFileName,const TDesC& aPath=KNullDesC);

Description

Loads the named DLL. If successful, the function increments the usage count by one.

Parameters

const TDesC& aFileName

A descriptor containing the name of the DLL to be loaded. The length of the file name must not be greater than KMaxFileName.

const TDesC& aPath

A descriptor containing a list of path names, each separated by a semicolon. When specified, these paths are searched for the DLL before the standard search locations. By default, no pathnames are specified.

Return value

TInt

KErrNone, if successful KErrBadName, if the length of aFileName is greater than KMaxFileName otherwise one of the system wide error codes

[Top]

Unloading DLLs

Close()

void Close();

Description

Closes this DLL. The function decrements the usage count by one.

This handle must have been used to load the DLL using one of the Load() functions.

[Top]

Using a loaded DLL

Lookup()

TLibraryFunction Lookup(TInt anOrdinal) const;

Description

Returns a pointer to the function at the specified ordinal within this DLL.

Parameters

TInt anOrdinal

The ordinal of the required function in this DLL. This value must be greater than zero, otherwise the function raises a USER 116 panic.

Return value

TLibraryFunction

A pointer to the function at position anOrdinal in this DLL. The value is NULL if there is no function at that ordinal.

Type()

TUidType Type() const;

Description

Returns this DLL's UID type.

The UID type is a property of a Symbian OS file; for a DLL, its value is set during the building of that DLL.

Return value

TUidType

The UID type of this DLL. Note that the first TUid component of the TUidType has the value KDynamicLibraryUid.

EntryPoint()

TLibraryEntry EntryPoint() const;

Description

Returns this DLL's entry point.

Return value

TLibraryEntry

A pointer to this DLL's entry point

FileName()

TFileName FileName() const;

Description

Returns the name of this DLL's file.

Return value

TFileName

This DLL's filename

GetRamSizes()

TInt GetRamSizes(TInt& aCodeSize, TInt& aConstDataSize);

Description

Gets the current size of the code and the const data for this DLL. This function can be called on a RAM loaded DLL or a ROM based DLL.

Parameters

TInt& aCodeSize

The current size of the code for a RAM loaded DLL. This is zero for a ROM based DLL

TInt& aConstDataSize

The current size of the const data for a RAM loaded DLL. This is zero for a ROM based DLL

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.

DllRefTable()

TUint* DllRefTable() const;

Description

Returns a pointer to this DLL's reference table.

Return value

TUint*

A pointer to this DLL's reference table. This is NULL, if this DLL has no reference table.

LibraryCallList()

TInt LibraryCallList(TInt& aNumEps, TUint*& aCallList);

Support

Withdrawn in 6.0

Description

Gets a list of entrypoints which become inaccessible to the current thread when this DLL is unloaded.

Parameters

TInt& aNumEps

On entry, the number of pointer locations provided by the caller at aCallList. On return, the number of entry points supplied.
TUint*& aCallList

A reference to contiguous memory sufficiently big to hold aNumEps pointers. This is provided by the caller. On return, the list of entrypoints.

Return value

TInt

KErrNone if successful; KErrGeneral if the number of entrypoints returned by the function is the same as the number of pointer locations supplied by the caller. This is a hint that there may be more entrypoints than there is space to rertun them. otherwise, one of the system wide error codes.

©2002 Symbian Ltd.

[Top]