/**

@page cryptotokens_TSecdlg tsecdlg - The dummy security dialog notifier

@section tsecdlg_intro Introduction

This document describes tsecdlg, the dummy security dialog notifier.

The security dialog API provides a way for components to ask the user various
standard security-related questions.  For example, it contains methods to prompt
the user to enter a passphrase, among others.  The API is defined in the file
secdlg.h.

It is necessary to write test harnesses for clients of this API which can be run
unattended, without user intervention.  To achieve this, tsecdlg was developed.
It allows user responses to security dialogs to be pre-defined, and enables a
test harness to check that the expected dialogs would have been displayed to the
user.

@section tsecdlg_secdlg_implementation Security dialog implementation

The dialogs that the user sees cannot be implemented as part of the security
subsystem because they form part of the user interface layer.  So the security
dialog API passes client requests to the security dialog notifier.  This is a
type of plugin, and is typically supplied by the UI implementation - for example
by techview.  The protocol used to pass messages to and from the plugin is
defined in the file secDlgImplDefs.h.

tsecdlg is just an implementation of the security dialog notifier that doesn't
ask the user for information.  Instead it either gives default responses or
reads them from a file.

@section tsecdlg_when_to_use_tsecdlg When it's necessary to use tsecdlg

Any test that directly or indirectly uses the security dialog API will require
the use of tsecdlg if the tests are to be run unattended.  At the moment, the
keystore is the main client of this API.  The keystore tests rely heavily on
tsecdlg, and anything that uses keystore will probably need to use it as well -
for example TLS.

<hr>

@section tsecdlg_preparation Preparation for running tests that use tsecdlg

@section tsecdlg_building_tsecdlg Building tsecdlg

Two versions of tsecdlg are built on all platforms - one for the extended
notifier framework (ie graphical notifiers, or techview) and one for textshell.
This means that tests will work in both environments.

To build tsecdlg just requires building the test code supplied in the
security cryptotokens component, eg:

\code
cd common\generic\security\cryptotokens\group
bldmake bldfiles
abld test build wins udeb
\endcode

There are two tsecdlg components: 

<table>
<tr><th>Name</th><th>Location</th><th>Description</th></tr>
<tr><td>t_secdlg</td><td>z:\\system\\notifiers\\tsecdlg.dll</td><td>Extended notifier</td></tr>
<tr><td>t_secdlg_text</td><td>z:\\system\\tnotifiers\\tsecdlg_text.dll</td><td>Textshell notifier</td></tr>
</table>

@section tsecdlg_emulator_testing Testing on the emulator 

If you are running in techview mode, you must ensure that the techview
implementation of the security dialog notifier (secdlg.dll) is not present (if
both secldg.dll and tsecdlg.dll are present, epoc will crash).  This can be
found in in z:\\system\\notifiers, for example
\\epoc32\\release\\wins\\udeb\\z\\system\\notifiers for wins udeb.  The easiest
way to ensure secdlg.dll is removed is to use the following command:

\code
del /s /f /q \epoc32\secdlg.dll
\endcode

This does not matter for textshell mode, because there is no default textshell
security dialog plugin.

@section tsecdlg_hardware_testing Testing on hardware

To test on hardware, the appropriate dll (either techview or textshell) must be
included in the ROM in the same location as it is in the emulator (ie
z:\\system\\notifiers for techview mode).  This can be done adding the following
line to an iby file:

\code
file=ABI_DIR\BUILD_DIR\tsecdlg.dll		System\Notifiers\tsecdlg.dll
\endcode

This is done for security tests in the file filetokenstests.iby.

Note that if you are using techview mode, you must ensure that secdlg.dll is not
included - you must edit \\epoc32\\rom\\include\\secui.iby and comment out the
following line:

\code
file=ABI_DIR\BUILD_DIR\secdlg.dll		System\Notifiers\Secdlg.dll
\endcode

<hr>

@section tsecdlg_cryptotokens_operation tsecdlg operation

tsecdlg has two modes of operation:

@li Default mode
@li Scripted mode

@section tsecdlg_default_mode Default mode

This is the simpler mode.  Whenever the dialog for a passphrase is triggered,
tsecdlg replies with a default passphrase ('pinkcloud').

This is intended to used by test code that is not directly testing a client of
the security dialog API, for example by TLS.

tsecdlg runs in this mode when the files c:\\t_secdlg_in.dat and
c:\\t_secdlg_out.dat are not present.

@section tsecdlg_scripted_mode Scripted mode

This mode is more complex, and is intended to be used by for testing direct
clients of the security dialog API - for example the keystore.

Before a test is run, a file of expected dialogs and the required responses is
prepared.  Every time the security dialog API is called and tsecdlg invoked, it
checks that the requested dialog is the one expected, and answers with the
pre-determined response.  An unexpected dialog request produces an error.  A
file containing the number of correctly answered dialog requests is maintained
and this allows the test harness to determine whether all expected dialogs were
triggered correctly.

The list of expected dialogs is read from c:\\t_secdlg_in.dat.  This has the
following format:

<table>
<tr><th>Type</th><th>Description</th></th>
<tr><td>TInt32</td><td>Number of dialogs expected</td></tr>
</table>

Then, for every expected dialog, the following data is present.  Strings are
represented with their size (TInt32) followed by that many bytes of data.

<table>
<tr><th>Type</th><th>Description</th></tr>
<tr><td>TInt32</td><td>Expected operation</td></tr>
<tr><td>String</td><td>Expected label</td></tr>
<tr><td>String</td><td>Response 1</td></tr>
<tr><td>String</td><td>Response 2 (not always used)</td></tr>
</table>

The expected operation should be a member of the TSecurityDialogOperation
enumeration - this specifies the expected type of dialog that is requested (for
example, the enter passphrase dialog).  If the requested operation is not the
same as this, the operation is completed with KErrOperationMismatch.  If the
operation is one that is not supported by tsecdlg (only the ones necessary for
testing keystore are currently implemented), the operation is completed with
KErrOperationNotSupported.

The expected label allows the test code to specify the label passed to the API.
It is matched if the actual label contains the expected label - this means that
passing an empty string will always ensure a match.  If the expected label is
not matched, the operation is completed with KErrLabelMismatch.

The responses are the information tsecdlg passes back as if from the user.  Some
operations (eg change PIN) return two pieces of information, but for the most
part only the first one is used.  

The error codes are summarised below.  Note that as this is test code, these are
not officially allocated!

<table>
<tr><th>Name</th><th>Code</th><th>Description</th></tr>
<tr><td>KErrTooManyDialogs</td><td>-12000</td><td>More dialogs have been requested than are described in the input file</td></tr>
<tr><td>KErrLabelMismatch</td><td>-12001</td><td>The label requested did not match the expected value</td></tr>
<tr><td>KErrOperationMismatch</td><td>-12002</td><td>The operation requested did not match the expected value</td></tr>
<tr><td>KErrOperationNotSupported</td><td>-12003</td><td>The operation requested is not implemented by tsecdlg</td></tr>
</table>

Every time a request is succesfully answered, the file c:\\t_secdlg_out.dat is
updated - it contains a single TInt32 that indicates the index of the current
dialog in the list of expected dialogs described by c:\\t_secdlg_in.dat.  If it
is not present, its value is assumed to be zero.

*/