Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: banamedplugins.h
Link against: bafl.lib

Class CBaNamedPlugins

class CBaNamedPlugins : public CBase, public MDesC16Array;

Description

A localised list of the names of the plug-ins available on the phone for a particular plug-in framework.

This class should be used by applications that display lists of plug-ins. It is provided so that the plug-in names displayed to users:

are not filenames

are localisable, i.e. for a multi-language ROM device, plug-in names must be translated into the correct language and sorted according to the locale's collation rules

can be filtered depending on the current locale, i.e. the user will not necessarily see the names of all plug-ins for a given framework for every language of a multi-language ROM.

Note that the class MDesC16Array is shown in the derivation tree. The class definition for CBaNamedPlugins, however, uses the typedef MDesCArray. In 6.1 builds, the symbol MDesCArray always resolves to MDesC16Array.

Derivation

Members

Defined in CBaNamedPlugins:
CParameters, EArrayPositionFirst, EArrayPositionLast, IdentifierAtIndex(), IndexOfIdentifier(), IndexOfUid(), MFallBackName, MdcaCount(), MdcaPoint(), NewL(), NewLC(), TArrayPosition, TCompareNames, TEquivalentIdentifiers, TResourceFile, UidAtIndex(), ~CBaNamedPlugins()

Inherited from CBase:
Delete(), Extension_(), operator new()


Construction and destruction


NewL()

static IMPORT_C CBaNamedPlugins *NewL(const CParameters &aParameters);

Description

Allocates and constructs a new list of plug-in names. The list is populated using the CParameters object passed into the function. The CParameters object can be destroyed once the CBaNamedPlugins object has been created.

Parameters

const CParameters &aParameters

The parameters for the list of plug-in names.

Return value

CBaNamedPlugins *

The new list of plug-in names.


NewLC()

static IMPORT_C CBaNamedPlugins *NewLC(const CParameters &aParameters);

Description

Allocates and constructs a new list of plug-in names. The list is populated using the CParameters object passed into the function. The list is left on the cleanup stack. The CParameters object can be destroyed once the CBaNamedPlugins object has been created.

Parameters

const CParameters &aParameters

The parameters for the list of plug-in names.

Return value

CBaNamedPlugins *

The new list of plug-in names.


~CBaNamedPlugins()

virtual IMPORT_C ~CBaNamedPlugins();

Description

Destructor. Deletes all resources owned by the object prior to its destruction.

[Top]


Member functions


IndexOfUid()

IMPORT_C TInt IndexOfUid(TUid aUid) const;

Description

Gets the index into the sorted list (i.e. the index into the MDesCArray) of the plug-in associated with the UID specified.

Parameters

TUid aUid

A plug-in UID to search for. Its value must not be KNullUid or a panic occurs.

Return value

TInt

The index into the list of the plug-in with the UID specified, or KErrNotFound if no plug-in has the specified UID.


IndexOfIdentifier()

IMPORT_C TInt IndexOfIdentifier(const TDesC &aIdentifier, TEquivalentIdentifiers aEquivalentIdentifiers) const;

Description

Gets the index into the sorted list (i.e. the index into the MDesCArray) of the plug-in associated with the identifier specified.

Parameters

const TDesC &aIdentifier

The plug-in identifier to search for.

TEquivalentIdentifiers aEquivalentIdentifiers

A function which tests whether two plug-in identifiers are the same, returning true or false.

Return value

TInt

The index into the list of the plug-in with the identifier specified, or KErrNotFound if no plug-in has the specified identifier.


UidAtIndex()

IMPORT_C TUid UidAtIndex(TInt aIndex) const;

Description

Gets the UID of the plug-in at the specified index into the MDesCArray.

Parameters

TInt aIndex

The index into the MDesCArray. Must be within the bounds of the array, or a panic occurs.

Return value

TUid

The UID of the plug-in at the specified index.


IdentifierAtIndex()

IMPORT_C const TDesC *IdentifierAtIndex(TInt aIndex) const;

Description

Gets the identifier of the plug-in at the specified index into the MDesCArray.

Parameters

TInt aIndex

The index into the MDesCArray. Must be within the bounds of the array, or a panic occurs.

Return value

const TDesC *

The identifier of the plug-in at the specified index.


MdcaCount()

virtual IMPORT_C TInt MdcaCount() const;

Description

Gets the number of plug-ins in the list.

Return value

TInt

The number of plug-ins in the list.


MdcaPoint()

virtual IMPORT_C TPtrC MdcaPoint(TInt aIndex) const;

Description

Returns a TPtrC for the name of the plug-in at the given index.

Parameters

TInt aIndex

The index into the list. Must be within the bounds of the array, or a panic occurs.

Return value

TPtrC

The name of the plug-in at the given index.

[Top]


Member classes


Class TResourceFile

class TResourceFile;

Description

Information about a resource file containing the names of one or more named plug-ins.

The information is the full filename of the resource file (the language-specific version of this file provides the localised names, for display to users), the format for the contents of the resource file and a unique identifier for the plug-in, which is either a UID or an arbitrary textual identifier (this is not for display).

An array of TResourceFile objects is passed to CParameters::NewL() and NewLC().

Members

Defined in CBaNamedPlugins::TResourceFile:
EFormatArrayOfUidNamePairs, EFormatTbuf, TFormat, iFormat, iFullFileName, iIdentifier, iUid

Member enumerations


Enum TFormat

TFormat

Description

The format of the contents of a resource file.

The EFormatArrayOfUidNamePairs format enables the names of multiple plug-ins to be held in a single resource file. This could be used in situations where a fixed set of plug-ins are provided in a single package, e.g. the plug-ins provided in a ROM (helping to reduce ROM space). In other cases, the EFormatTbuf format should be used (here a single resource file provides the name of a single plug-in).

EFormatTbuf

The resource file contains a single TBUF (text string) resource, to hold the plug-in name.

EFormatArrayOfUidNamePairs

The resource file contains an ARRAY resource, whose items are UID_NAME_PAIR structs. These contain plug-in UID and name pairs.

Member data


iFullFileName

HBufC * iFullFileName;

Description

The full filename of the resource file, with a language-independent extension (i.e. .rsc rather than, for instance, .r12). The language-specific version of this file (with the correct language extension) contains the localised name of the plug-in. The BaflUtils class is used internally to create the correct language extension for iFullFileName.

See also:


iIdentifier

HBufC * iIdentifier;

Description

Optional unique identifier for the plug-in , for instance the filename of the plug in's DLL. If not applicable, it may be NULL.


iUid

TUid iUid;

Description

Optional plug-in UID. If not applicable, it may have a value of KNullUid.


iFormat

TFormat iFormat;

Description

The format of the resource file's contents.


Class MFallBackName

class MFallBackName;

Description

Interface class with a single pure virtual function that generates a fallback name for plug-ins.

The FallBackNameL() function is called during construction of the CBaNamedPlugins object for any plug-ins for which no resource file could be found with the correct language extension.

Use of this interface is optional. To use it, pass an instance of a class which implements the interface to CParameters::SetFallBackName(). If this is not done, then by default the fallback name used for plug-ins is simply the filename of the resource file without the drive, directory path or extension.

Members

Defined in CBaNamedPlugins::MFallBackName:
FallBackNameL()

Member functions


FallBackNameL()

virtual HBufC *FallBackNameL(const TDesC &aFullResourceFileName) const=0;

Description

Generates and returns a fallback name for plug-ins for which no resource is available. The fallback name can be generated using the filename of the plug-in's resource file, which is passed as an argument.

Parameters

const TDesC &aFullResourceFileName

The full filename of the resource file. This is the same as TResourceFile::iFullFileName.

Return value

HBufC *

The fallback name for a plug-in.


Class CParameters

class CParameters : public CBase;

Description

The parameters for a localised list of plug-in names.

An object of this class is passed to CBaNamedPlugins::NewL() and NewLC(). The parameters are as follows - minimally, the first two must be provided:

An array of TResourceFile objects. Each object contains information about a single plug-in, or multiple plug-ins, including the filename of the corresponding resource file. Versions of these resource files with the correct filename extensions for the required languages provide the name of one or more plug-in, translated appropriately.

A connected session with the file server. This is required to search the file sytem for the localised resource files, then to open them for reading.

An optional object that generates a fallback name for plug-ins, if no resource file could be found. If no such function is provided, then the fallback name used for plug-ins is simply the filename of the resource file without the drive, directory path or extension.

An optional function that compares two plug-in names for sorting. The list is sorted after it has been fully populated, using this algorithm. If not specified, sorting is done by using the system-wide (locale-dependent) collation rules.

An optional descriptor which, if provided, adds an additional item whose meaning is "none" (i.e. "no plug-in") to the MDesCArray, and the array position (either the start or the end of the array) at which to insert it.

Derivation

Members

Defined in CBaNamedPlugins::CParameters:
NewL(), NewLC(), SetCompareNames(), SetFallBackName(), SetTextForNone(), SetTextForNoneL(), ~CParameters()

Inherited from CBase:
Delete(), Extension_(), operator new()

Construction and destruction


NewL()

static IMPORT_C CParameters *NewL(RFs &aFileServerSession, const TArray< TResourceFile > &aArrayOfResourceFiles);

Description

Allocates and constructs a new parameters object.

Parameters

RFs &aFileServerSession

A connected session with the file server. This is required to search the file sytem for the localised resource files, and to open them for reading.

const TArray< TResourceFile > &aArrayOfResourceFiles

Array of TResourceFile objects. Each object contains information about a single plug-in, if its iFormat attribute is set to EFormatTbuf or potentially multiple plug-ins if its iFormat attribute is set to EFormatArrayOfUidNamePairs. This information includes the filename of its resource file. The CParameters object takes a copy of this array.

Return value

CParameters *

The new parameters object.


NewLC()

static IMPORT_C CParameters *NewLC(RFs &aFileServerSession, const TArray< TResourceFile > &aArrayOfResourceFiles);

Description

Allocates and constructs a new parameters object. The object is left on the cleanup stack.

Parameters

RFs &aFileServerSession

A connected session with the file server. This is required to search the file sytem for the localised resource files and to open them for reading.

const TArray< TResourceFile > &aArrayOfResourceFiles

Array of TResourceFile objects. Each object contains information about a single plug-in, if its iFormat attribute is set to EFormatTbuf or potentially multiple plug-ins if its iFormat attribute is set to EFormatArrayOfUidNamePairs. This information includes the filename of its resource file. The CParameters object takes a copy of this array.

Return value

CParameters *

The new parameters object.


~CParameters()

virtual IMPORT_C ~CParameters();

Description

Destructor. Deletes all resources owned by the object.

Member functions


SetFallBackName()

IMPORT_C void SetFallBackName(const MFallBackName &aFallBackName);

Description

Sets a function that generates a fallback name for plug-ins for which no resource file could be found. If SetFallBackName() is not called, then by default the fallback name used for plug-ins is simply the filename of the resource file without the drive, directory path or extension.

Parameters

const MFallBackName &aFallBackName

An instance of an MFallBackName-derived class. This should implement a function which creates a name for plug-ins for which there is no resource available (the "fallback" name).


SetCompareNames()

IMPORT_C void SetCompareNames(TCompareNames aCompareNames);

Description

Sets a function that compares two plug-in names for sorting. The plug-in names list is sorted after it has been fully populated, using this algorithm. If SetCompareNames() is not called, collation takes place by default using TDesC::CompareC().

Parameters

TCompareNames aCompareNames

A function that compares two plug-in names for sorting.


SetTextForNoneL()

IMPORT_C void SetTextForNoneL(const TDesC &aTextForNone, TArrayPosition aArrayPositionOfTextForNone);

Description

Sets a text string, representing the choice of no plug-in and the array position at which to insert it. This function increases the length of the plug-in names list by one because it creates and adds an item to the array which is empty except for the text string specified.

Parameters

const TDesC &aTextForNone

The string whose meaning is "none", i.e. no plug-in. It is assumed that this descriptor has already been localised.

TArrayPosition aArrayPositionOfTextForNone

Whether the string should be inserted at the start or appended to the end of the array.


SetTextForNone()

IMPORT_C void SetTextForNone(HBufC *aTextForNone, TArrayPosition aArrayPositionOfTextForNone);

Description

Sets a text string, representing the choice of no plug-in and the array position at which to insert it. This function increases the length of the plug-in names list by one because it creates and adds an item to the array which is empty except for the text string specified. The function cannot leave because nothing is allocated ownership of aTextForNone is passed to the CParameters object.

Parameters

HBufC *aTextForNone

The string whose meaning is "none", i.e. no plug-in. It is assumed that this descriptor has already been localised.

TArrayPosition aArrayPositionOfTextForNone

Whether the string should be inserted at the start or appended to the end of the array.

[Top]


Member enumerations


Enum TArrayPosition

TArrayPosition

Description

The position in the list of plug-in names for the text string which represents the choice of no plug-in.

Passed as an argument to SetTextForNoneL() and SetTextForNone().

EArrayPositionFirst

The string is inserted at the start of the list (array position zero).

EArrayPositionLast

The string is appended to the list.

[Top]


Member type definitions


Typedef TCompareNames

typedef TInt(* CBaNamedPlugins::TCompareNames)(const TDesC& aName1, const TDesC& aName2);

Description

The prototype for a function that compares two plug-in names, aName1 and aName2 for sorting.

The plug-in names list is sorted using this algorithm after it has been populated. Implementing this function is optional. If implemented, it is passed as a parameter to CParameters::SetCompareNames(). If not implemented, a default algorithm is used.

The function should return a positive value if aName1 is to occur after aName2 or negative if aName1 is to occur before aName2. Zero should be returned if both descriptors are equivalent.


Typedef TEquivalentIdentifiers

typedef TBool(* CBaNamedPlugins::TEquivalentIdentifiers)(const TDesC& aIdentifier1, const TDesC& aIdentifier2);

Description

The prototype for a function that compares two plug-in identifiers, aIdentifier1 and aIdentifier2 to find out if they are the same.

Implementing this function is optional. If implemented, it is passed to CBaNamedPlugins::IndexOfIdentifier(), which uses the function to compare a specified plug-in identifier with each identifier in turn in the list of named plug-ins. The function should return ETrue if they are the same, EFalse if not. TDesC::CompareC() could be used to do the comparison.

See also: