Collapse all Symbian^3 Product Developer Library

How to use a polymorphic interface DLL

The example issues a greeting to the person whose name is passed in the descriptor aName.

The following code can use any implementation of the interface defined by the example class, CMessenger, to issue a simple greeting.

The name of the DLL, which contains the implementation to be used, is passed in the descriptor aLibraryName.

void UseDllL(const TFileName& aLibraryName,const TDesC& aName)
    {
          // Use RLibrary object to interface to the DLL
    RLibrary library;
          // Dynamically load the DLL
    TUidType uidType(KDynamicLibraryUid,KMessengerUid);
    User::LeaveIfError(library.Load(aLibraryName,uidType));
          // Function at ordinal 1 creates new CMessenger
    TLibraryFunction entry=library.Lookup(1);
          // Call the function to create new CMessenger
    CMessenger* messenger=(CMessenger*) entry();
          // Push pointer to CMessenger onto the cleanup stack
    CleanupStack::PushL(messenger);
          // Second-phase constructor for CMessenger
    messenger->ConstructL(console, aName);
          // Use Cmessenger object to issue greeting
    messenger->ShowMessage();
          // Pop CMessenger object off cleanup stack and destroy
    CleanupStack::PopAndDestroy();
          // Finished with the DLL
    library.Close();
    }

Notes:

the RLibrary class is the interface to dynamically loaded DLLs. It encapsulates a handle to the DLL.
The DLL has a TUidType which is assigned when the DLL is built. This is ensures that the DLL that is loaded complies with the CMessenger protocol.
If a specific implementation of the DLL is to be used, then specify a third UID when declaring the TUidType. Each specific implementation of the DLL is uniquely identified by the third UID.
A pointer to the ordinal 1 function in the DLL is fetched by calling the Lookup() member function of RLibrary and passing it a parameter value of 1. The returned function has type TLibraryFunction; such a function takes no parameters and returns a TAny* type.
The function pointer is assigned to the variable called entry and the function itself is called to construct a CMessenger object and return a pointer to that object. The implementation uses the new (ELeave) operator to allocate the new CMessenger object and invoke the C++ default constructor.
As no arguments are passed to the function, a second-phase constructor, ContructL(), is called to finish off construction.
The CMessenger object can then be used like any other C++ object. In this example, the ShowMessage() function is used to emit a greeting in whatever way the implementation chooses. In more complex cases, the object could have a long lifetime, and create many dependent objects.
When the CMessenger object is no longer needed, the DLL is unloaded using RLibrary::Close(). Do not call any code in the DLL after the library has been closed. It is important to note, therefore, that the library must not be closed until the object constructed by the DLL, and all its dependent objects, have been destroyed.

Parent topic: Dynamically loading link libraries