Kannabiran’s Weblog

Overview

This code snippet demonstrates how to display a manufacturer disclaimer when an application is launched for the first time. This behavior is required at least for VoIP applications that are meant to be sent to Symbian for signing.

In practice, the requested behavior is implemented by deleting the disclaimer file after it has been accepted for the first time. Every time the application is run, it is checked whether or not the file exists.

This snippet can be self-signed.

data\disclaimer.txt

Here is an example of the disclaimer text by Symbian for VoIP applications:

You are about to use <APPLICATION NAME>, which is
developed and owned by <YOUR COMPANY NAME>. The
manufacturer of this device shall have no liability for
any aspect of the application whatsoever, including its
performance, call routing, intellectual property rights
or support.

PKG file

Install the disclaimer file to the device by adding the following line to the PKG file:

"..\data\disclaimer.txt" - "!:\private\E9D7CF12\disclaimer.txt"

MMP file

The following libraries are required:

LIBRARY  bafl.lib

RSS file

RESOURCE DIALOG r_disclaimer_dialog
    {
    flags = EGeneralQueryFlags | EEikDialogFlagNoBorder | EEikDialogFlagNoShadow;
    buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
    items=
        {
        DLG_LINE
            {
            type = EAknCtPopupHeadingPane;
            id = EAknMessageQueryHeaderId;
            itemflags = EEikDlgItemNonFocusing;
            control = AVKON_HEADING
                {
                headinglayout = R_AVKON_WML_SIGN_QUERY_HEADING_PANE;
                };
            },
        DLG_LINE
            {
            type = EAknCtMessageQuery;
            id = EAknMessageQueryContentId;
            control = AVKON_MESSAGE_QUERY
                {
                };
            }
        };
    }

Header file

public:  // Constructors and destructor
        /**
         * 2nd phase constructor.
         */
        void ConstructL();

    private:  // New methods
        /**
         * Shows the disclaimer dialog.
         * @return ETrue if the user accepts the disclaimer; EFalse if not.
         */
        TBool ShowDisclaimerL(RFs& aFs, const TDesC& aFilename);
         /** 
         * Deletes the disclaimer file.
         */
        void DeleteDisclaimerL(RFs& aFs, const TDesC& aFilename);

Source file

#include <aknmessagequerydialog.h>  // CAknMessageQueryDialog
#include <BAUTILS.H> // BaflUtils
#include <EIKENV.H>  // CEikonEnv
void CMyAppUi::ConstructL()
    {
    // Initialize the UI. This has to be done before the disclaimer dialog is
    // shown.
    BaseConstructL(CAknAppUi::EAknEnableSkin);

    // Connect to the file server session
    RFs fsSession;
    User::LeaveIfError(fsSession.Connect());
    CleanupClosePushL(fsSession);

    // The disclaimer file
    _LIT(KFilename, "C:\\private\\E9D7CF12\\disclaimer.txt");

    // If the disclaimer file exists, the application hasn't been run yet
    if (BaflUtils::FileExists(fsSession, KFilename))
        {
        // Show the disclaimer dialog
        TBool selectedOption;
        TRAPD(showErr, selectedOption = ShowDisclaimerL(fsSession, KFilename));
        if (showErr != KErrNone)
            {
            // TODO: Error handling
            }
        if (!selectedOption)
            {
            // The user canceled the disclaimer dialog. Exit the application.
            CleanupStack::PopAndDestroy();  // fsSession
            Exit();
            }
        else
            {
            // The user continued with the application launch.
            // Delete the disclaimer file so that it won't be around the next time the
            // application is run.    
            TRAPD(deleteErr, DeleteDisclaimerL(fsSession, KFilename));
            if (deleteErr != KErrNone)
                {
                // TODO: Error handling
                }
            }
        }

    CleanupStack::PopAndDestroy();  // fsSession

    // ...
}
TBool CMyAppUi::ShowDisclaimerL(RFs& aFs, const TDesC& aFilename)
    {
    // Open the disclaimer text file
    RFile file;
    TInt openError = file.Open(aFs, aFilename, EFileRead);
    if (openError != KErrNone)
        {
        _LIT(KErrMsg, "Cannot open the disclaimer file for reading.");
        _LIT(KExitingApp, "Exiting app.");
        CEikonEnv::Static()->InfoWinL(KErrMsg, KExitingApp);
        User::Leave(openError);
        }
    CleanupClosePushL(file);

    // Read file size
    TInt fileSize = 0;
    TInt sizeError = file.Size(fileSize);
    if (sizeError != KErrNone)
        {
        CleanupStack::PopAndDestroy();  // file
        User::Leave(sizeError);
        }

    // Read file contents
    HBufC8* disclaimerText8 = HBufC8::NewLC(fileSize);
    TPtr8 disclaimerPtr = disclaimerText8->Des();
    TInt ioError = file.Read(disclaimerPtr, fileSize);
    if (ioError != KErrNone)
        {
        CleanupStack::PopAndDestroy(2);  // disclaimerText8, file
        User::Leave(ioError);
        }

    // Done with the file. Close it.
    file.Close();

    // Convert the 8-bit disclaimer text to 16-bit
    HBufC* disclaimerText = HBufC::NewLC(disclaimerText8->Length());
    disclaimerText->Des().Copy(*disclaimerText8);

    // Show the disclaimer dialog
    _LIT(KTitle, "MyApplication");
    CAknMessageQueryDialog* dlg = CAknMessageQueryDialog::NewL(*disclaimerText);
    CleanupStack::PushL(dlg);
    dlg->PrepareLC(R_DISCLAIMER_DIALOG);
    dlg->SetHeaderTextL(KTitle);
    CleanupStack::Pop(dlg);

    TBool result = dlg->RunLD();

    CleanupStack::PopAndDestroy(3);  // disclaimerText, disclaimerText8, file

    return result;
    }
void CMyAppUi::DeleteDisclaimerL(RFs& aFs, const TDesC& aFilename)
    {
    // Delete the disclaimer file
    TInt deleteError = BaflUtils::DeleteFile(aFs, aFilename);
    if (deleteError != KErrNone)
        {
        User::Leave(deleteError);
        }
    }

Postconditions

A manufacturer disclaimer is displayed when the application is launched for the first time. The user is given the option to continue with the launch or abort it. If the user decides to accept the disclaimer, the disclaimer file is deleted from the device.

Overview

This code snippet demonstrates how to display a manufacturer disclaimer when an application is being installed. This behavior is required at least for VoIP applications that are meant to be sent to Symbian for signing.

This snippet can be self-signed.

data\disclaimer.txt

This is an example of the disclaimer text by Symbian for VoIP applications:

You are about to use <APPLICATION NAME>, which is
developed and owned by <YOUR COMPANY NAME>. The
manufacturer of this device shall have no liability for
any aspect of the application whatsoever, including its
performance, call routing, intellectual property rights
or support.

PKG file

To display the disclaimer to the user, add the following line to the PKG file of your application:

"..\data\disclaimer.txt" - "", FILETEXT, TEXTEXIT

The FILETEXT install option indicates that a file is to be displayed to the user during the installation procedure. The file itself is not installed on the target device (the target location is empty).

The TEXTEXIT install option displays a dialog box with “positive” and “negative” buttons, such as Ok and Cancel. If the dialog returns true (the user pressed Ok), the software installer continues with the installation. If the dialog returns false (the user pressed Cancel), the software installer is exited and any files that have already been installed are removed.

Postconditions

A manufacturer disclaimer is displayed when the application is installed. The user is given the option to continue with the installation or abort it.