CLiwServiceHandler Class Reference

class CLiwServiceHandler : public CBase

CLiwServiceHandler is the main class of the Language Interworking Framework. The Service Handler implements support for dynamically loadable service providers which offer services to consumer applications. The Service Handler maps consumers and service providers together via interests and data agreements and hides the consumers from the providers.

SERVICE is any command or functionality offered by a provider to consumer. The service includes typically menu item UI elements, but it can also just an engine type of command which executes specific functionality and reports status back to the consumer.

CONSUMER application accesses interesting services offered by service provider(s). The consumer uses only those services in which it is interested in. The interest is expressed using a set of criteria items.

INTEREST is a list of criteria items.

CRITERIA consists of set of attributes which guide the LIW Framework to use only those providers in which the consumer is interested in. The criteria consists of following attributes:
  • Criteria UID (we can allocate pre-defined criteria items).

  • Service command UID (we can allocate pre-defined commands).

  • Content MIME type (string).

  • Additional options (variant data type just in case).

PROVIDER produces those services for a consumer that match the given criteria specified by the consumer. A provider can offer menu items and their command handling logic to the consumer applications. A provider can also offer base services that don't require any UI elements.

DATA AGREEMENT is an agreement between consumer and provider about parameters needed to be passed in a use case.

ServiceHandler.lib
Since
Series 60 2.6

Inherits from

Public Member Functions
~CLiwServiceHandler()
IMPORT_C voidAttachL(TInt)
IMPORT_C TIntAttachL(const RCriteriaArray &)
IMPORT_C TIntAttachL(const RCriteriaArray &, CRTSecMgrScriptSession &)
IMPORT_C voidAttachMenuL(TInt, TInt)
IMPORT_C voidAttachMenuL(TInt, TResourceReader &)
IMPORT_C voidAttachMenuL(TInt, const RCriteriaArray &)
IMPORT_C voidAttachMenuL(RArray< TInt > &, TInt, RCriteriaArray &)
IMPORT_C voidDetachL(const RCriteriaArray &)
IMPORT_C voidDetachL(TInt)
IMPORT_C voidDetachMenu(TInt, TInt)
IMPORT_C voidExecuteMenuCmdL(TInt, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)
IMPORT_C voidExecuteServiceCmdL(const TInt &, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)
IMPORT_C voidExecuteServiceCmdL(const CLiwCriteriaItem &, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)
IMPORT_C const CLiwCriteriaItem *GetCriteria(TInt)
IMPORT_C voidGetInterest(RCriteriaArray &)
IMPORT_C TBoolHandleSubmenuL(CEikMenuPane &)
IMPORT_C CLiwGenericParamList &InParamListL()
IMPORT_C voidInitializeMenuPaneL(CEikMenuPane &, TInt, TInt, const CLiwGenericParamList &)
IMPORT_C voidInitializeMenuPaneL(CEikMenuPane &, TInt, TInt, const CLiwGenericParamList &, TBool)
IMPORT_C TBoolIsLiwMenu(TInt)
IMPORT_C TBoolIsSubMenuEmpty(TInt)
IMPORT_C TIntMenuCmdId(TInt)
IMPORT_C TIntNbrOfProviders(const CLiwCriteriaItem *)
IMPORT_C CLiwServiceHandler *NewL()
IMPORT_C CLiwServiceHandler *NewLC()
IMPORT_C CLiwGenericParamList &OutParamListL()
IMPORT_C voidQueryImplementationL(RCriteriaArray &, RCriteriaArray &)
IMPORT_C voidReportMenuLaunch()
IMPORT_C voidReset()
IMPORT_C TIntServiceCmdByMenuCmd(TInt)
Private Member Functions
CLiwServiceHandler()
voidConstructL()
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
CLiwServiceHandlerImpl *iImpl

Constructor & Destructor Documentation

CLiwServiceHandler()

CLiwServiceHandler()[private]

~CLiwServiceHandler()

IMPORT_C~CLiwServiceHandler()[virtual]

Destructor.

Member Functions Documentation

AttachL(TInt)

IMPORT_C voidAttachL(TIntaInterestResourceId)

Adds the given interest to the Service Handler from a resource and updates possibly existing old interest. Corresponding service providers are loaded. If a provider leaves during initialization, it is trapped by the Service Handler.

leave
KErrNotSupported CCoeEnv is not accessible.
Reset

Parameters

TInt aInterestResourceIdID of the resource containing criteria items.

AttachL(const RCriteriaArray &)

IMPORT_C TIntAttachL(const RCriteriaArray &aInterest)

Adds given interest to the Service Handler from an array of criteria items. If a provider leaves during initialization, it is trapped by the Service Handler.

Parameters

const RCriteriaArray & aInterestArray of criteria items. Ownership is not transferred.

AttachL(const RCriteriaArray &, CRTSecMgrScriptSession &)

IMPORT_C TIntAttachL(const RCriteriaArray &aInterest,
CRTSecMgrScriptSession &aSecMgrScriptSession
)

Parameters

const RCriteriaArray & aInterest
CRTSecMgrScriptSession & aSecMgrScriptSession

AttachMenuL(TInt, TInt)

IMPORT_C voidAttachMenuL(TIntaMenuResourceId,
TIntaInterestResourceId
)

Attach menu related criteria items to the given menu. If a provider leaves during initialization, it is trapped by the Service Handler.

leave
KErrNotSupported CCoeEnv is not accessible.

Parameters

TInt aMenuResourceIdMenu to be attached.
TInt aInterestResourceIdResource id for the interest list.

AttachMenuL(TInt, TResourceReader &)

IMPORT_C voidAttachMenuL(TIntaMenuResourceId,
TResourceReader &aReader
)

Attach menu related criteria items to the given menu. If a provider leaves during initialization, it is trapped by the Service Handler.

leave
KErrNotSupported CCoeEnv is not accessible.

Parameters

TInt aMenuResourceIdMenu to be attached.
TResourceReader & aReaderResource reader for the interest list.

AttachMenuL(TInt, const RCriteriaArray &)

IMPORT_C voidAttachMenuL(TIntaMenuResourceId,
const RCriteriaArray &aInterest
)

Attach menu related criteria items to the given menu.

leave
KErrNotSupported CCoeEnv is not accessible.

Parameters

TInt aMenuResourceIdMenu to be attached.
const RCriteriaArray & aInterestArray of criteria items. Ownership is not transferred.

AttachMenuL(RArray< TInt > &, TInt, RCriteriaArray &)

IMPORT_C voidAttachMenuL(RArray< TInt > &aMenuEntries,
TIntaMenuResourceId,
RCriteriaArray &aInterest
)

Attach menu related criteria items to the given menu.

Parameters

RArray< TInt > & aMenuEntriesList of menu command ids, ids not related to interests may be set to 0.
TInt aMenuResourceIdMenu to be attached.
RCriteriaArray & aInterestInterest list.

ConstructL()

voidConstructL()[private]

DetachL(const RCriteriaArray &)

IMPORT_C voidDetachL(const RCriteriaArray &aInterest)

Removes given interest from the Service Handler. Corresponding service providers are unloaded.

Parameters

const RCriteriaArray & aInterestArray of returned criteria items, may be empty.

DetachL(TInt)

IMPORT_C voidDetachL(TIntaInterestResourceId)

Removes given interest from the Service Handler. Corresponding service providers are unloaded.

leave
KErrNotSupported CCoeEnv is not accessible.

Parameters

TInt aInterestResourceIdID of the resource containing criteria items.

DetachMenu(TInt, TInt)

IMPORT_C voidDetachMenu(TIntaMenuResourceId,
TIntaInterestResourceId
)

Detach menu related criteria items from the given menu. In following cases this method just returns without doing anything: 1. If interest resource id is non-zero and CCoeEnv is not accessible. 2. If interest resource id is non-zero and there occurs an error when reading the interest (e.g. not enough memory).

Parameters

TInt aMenuResourceIdMenu to be detached.
TInt aInterestResourceIdResource id for the interest list. If NULL, all criteria items are detached from the given menu.

ExecuteMenuCmdL(TInt, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)

IMPORT_C voidExecuteMenuCmdL(TIntaMenuCmdId,
const CLiwGenericParamList &aInParamList,
CLiwGenericParamList &aOutParamList,
TUintaCmdOptions = 0,
MLiwNotifyCallback *aCallback = NULL
)

Tells the provider to execute a menu command invoked by the consumer. Not supported if calling outside UI framework. Use ServiceCmdByMenuCmd to check if there is any provider for the menu command.

leave
KErrArgument Callback is missing when required.
leave
KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible.
ServiceCmdByMenuCmd

Parameters

TInt aMenuCmdIdThe menu command to be executed.
const CLiwGenericParamList & aInParamListInput data parameters, can be an empty list.
CLiwGenericParamList & aOutParamListOutput data parameters, can be an empty list.
TUint aCmdOptions = 0Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh.
MLiwNotifyCallback * aCallback = NULLCallback for asynchronous command handling, parameter checking, etc.

ExecuteServiceCmdL(const TInt &, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)

IMPORT_C voidExecuteServiceCmdL(const TInt &aCmdId,
const CLiwGenericParamList &aInParamList,
CLiwGenericParamList &aOutParamList,
TUintaCmdOptions = 0,
MLiwNotifyCallback *aCallback = 0
)

Executes a service command for all providers. Otherwise similar to ExecuteMenuCmdL.

leave
KErrArgument Callback is missing when required.
leave
KErrNotSupported No provider supports the service.

Parameters

const TInt & aCmdIdThe command to be executed.
const CLiwGenericParamList & aInParamListInput data parameters, can be an empty list.
CLiwGenericParamList & aOutParamListOutput data parameters, can be an empty list.
TUint aCmdOptions = 0Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh.
MLiwNotifyCallback * aCallback = 0Callback for asynchronous command handling, parameter checking, etc.

ExecuteServiceCmdL(const CLiwCriteriaItem &, const CLiwGenericParamList &, CLiwGenericParamList &, TUint, MLiwNotifyCallback *)

IMPORT_C voidExecuteServiceCmdL(const CLiwCriteriaItem &aCmd,
const CLiwGenericParamList &aInParamList,
CLiwGenericParamList &aOutParamList,
TUintaCmdOptions = 0,
MLiwNotifyCallback *aCallback = 0
)

Executes a service command.

leave
KErrArgument Callback is missing when required.
leave
KErrNotSupported No provider supports the service.

Parameters

const CLiwCriteriaItem & aCmdThe criteria item containing the service command and content type
const CLiwGenericParamList & aInParamListInput data parameters, can be an empty list.
CLiwGenericParamList & aOutParamListOutput data parameters, can be an empty list.
TUint aCmdOptions = 0Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh.
MLiwNotifyCallback * aCallback = 0Callback for asynchronous command handling, parameter checking, etc.

GetCriteria(TInt)

IMPORT_C const CLiwCriteriaItem *GetCriteria(TIntaId)

Returns criteria by ID.

Parameters

TInt aIdCriteria ID.

GetInterest(RCriteriaArray &)

IMPORT_C voidGetInterest(RCriteriaArray &aInterest)

Gets the currently valid interest in use by the Service Handler.

Parameters

RCriteriaArray & aInterestAn array of returned criteria items, may be empty. Ownership is not transferred, i.e. the objects in the array must not be deleted.

HandleSubmenuL(CEikMenuPane &)

IMPORT_C TBoolHandleSubmenuL(CEikMenuPane &aPane)

Handles LIW submenus. This method should be called from consumer application's DynInitMenuPaneL.

Parameters

CEikMenuPane & aPaneMenu pane to be handled.

InParamListL()

IMPORT_C CLiwGenericParamList &InParamListL()

Returns an empty instance of CLiwGenericParamList class. It can be used for example as an input parameter list for the Service Handler's API methods. This is just a convenience method and doesn't have to be used. If consumer wants to create input list by itself it is ok. If this method is used, the Service Handler takes care of deleting returned generic parameter list.

InitializeMenuPaneL(CEikMenuPane &, TInt, TInt, const CLiwGenericParamList &)

IMPORT_C voidInitializeMenuPaneL(CEikMenuPane &aMenuPane,
TIntaMenuResourceId,
TIntaBaseMenuCmdId,
const CLiwGenericParamList &aInParamList
)

Initialises menu pane with service commands from a provider. This method must be called upon DynInitMenuPaneL of consumer application in order to let the provider to hook its menu items.

leave
KErrNotSupported CCoeEnv is not accessible.
leave
KErrOverflow Consumer application has too many LIW placeholders in its menu. Currently, maximum 16 is supported.

Parameters

CEikMenuPane & aMenuPaneHandle of the menu pane to initialise.
TInt aMenuResourceIdThe menu to be attached.
TInt aBaseMenuCmdIdBase ID for the Service Handler to generate menu IDs for placeholders.
const CLiwGenericParamList & aInParamListInput parameter list for provider's parameters checking.

InitializeMenuPaneL(CEikMenuPane &, TInt, TInt, const CLiwGenericParamList &, TBool)

IMPORT_C voidInitializeMenuPaneL(CEikMenuPane &aMenuPane,
TIntaMenuResourceId,
TIntaBaseMenuCmdId,
const CLiwGenericParamList &aInParamList,
TBoolaUseSubmenuTextsIfAvailable
)

Initialises menu pane with service commands from a provider. This method must be called upon DynInitMenuPaneL of consumer application in order to let the provider to hook its menu items. In normal circumstances, the other variant of this method should be used.

leave
KErrNotSupported CCoeEnv is not accessible.
leave
KErrOverflow Consumer application has too many LIW placeholders in its menu. Currently, maximum 16 is supported.

Parameters

CEikMenuPane & aMenuPaneHandle of the menu pane to initialise.
TInt aMenuResourceIdThe menu to be attached.
TInt aBaseMenuCmdIdBase ID for the Service Handler to generate menu IDs for placeholders.
const CLiwGenericParamList & aInParamListInput parameter list for provider's parameters checking.
TBool aUseSubmenuTextsIfAvailableIf the provider has specified alternative submenu texts for its menu items, those can be taken into use if this parameter is set to ETrue. This should be used only for manually created submenus. If using LIW_CASCADE_ID or LIW_INTELLIGENT_CASCADE_ID, the LIW framework can automatically decide whether to use the submenu texts or not, and this parameter has no effect.

IsLiwMenu(TInt)

IMPORT_C TBoolIsLiwMenu(TIntaMenuResourceId)

Returns boolean value indicating whether the given menu contains currently attached placeholders.

Parameters

TInt aMenuResourceIdResource id of the menu to be queried.

IsSubMenuEmpty(TInt)

IMPORT_C TBoolIsSubMenuEmpty(TIntaSubMenuId)

Checks if there are menu providers attached to given menu id. Consumer application can use this information to decide whether a sub menu containing only LIW items should be hidden or not.

Parameters

TInt aSubMenuIdThe menu id to be checked.

MenuCmdId(TInt)

IMPORT_C TIntMenuCmdId(TIntaMenuCmdId)const

Gets provider command ID by dynamic command ID.

Since
Series 60 3.0

Parameters

TInt aMenuCmdIdThe consumer's menu command ID generated by LIW framework. This can be get e.g. from consumer's HandleCommandL().

NbrOfProviders(const CLiwCriteriaItem *)

IMPORT_C TIntNbrOfProviders(const CLiwCriteriaItem *aCriteria)

Returns the amount of providers that fulfil the given criteria.

Parameters

const CLiwCriteriaItem * aCriteriaCriteria to match.

NewL()

IMPORT_C CLiwServiceHandler *NewL()[static]

Constructs a Service Handler instance.

NewLC()

IMPORT_C CLiwServiceHandler *NewLC()[static]

Constructs a Service Handler instance.

OutParamListL()

IMPORT_C CLiwGenericParamList &OutParamListL()

Returns an empty instance of CLiwGenericParamList class. The instance can be used for example as an output parameter list for Service Handler API methods. This is just a convenience method and doesn't have to be used. If consumer wants to create output list by itself it is ok. If this method is used, Service Handler takes care of deleting returned generic parameter list.

QueryImplementationL(RCriteriaArray &, RCriteriaArray &)

IMPORT_C voidQueryImplementationL(RCriteriaArray &aFilterItem,
RCriteriaArray &aProviderList
)

Lists available service implementations

Parameters

RCriteriaArray & aFilterItem
RCriteriaArray & aProviderList

ReportMenuLaunch()

IMPORT_C voidReportMenuLaunch()[static]

CEikMenuPane uses this method to inform AIF framework that a menu is launched. This method does not need to be called by any other component.

Since
Series 60 3.0

Reset()

IMPORT_C voidReset()

Resets the Service Handler, discards existing interest and unloads corresponding service providers.

ServiceCmdByMenuCmd(TInt)

IMPORT_C TIntServiceCmdByMenuCmd(TIntaMenuCmdId)const

Returns the service command ID associated to the menu command. If found, it means that there is a provider which can handle the menu command. Thus the command handling needs to be routed to the provider via ExecuteMenuCmdL.

ExecuteMenuCmdL

Parameters

TInt aMenuCmdIdMenu command ID to be mapped to service cmd, KNullServiceCmd is returned if no service command exists.

Member Data Documentation

CLiwServiceHandlerImpl * iImpl

CLiwServiceHandlerImpl *iImpl[private]