CAiwServiceHandler Class Reference

API published in: S60 3rd Ed FP 2

Link against: servicehandler.lib

#include <aiwservicehandler.h>

Detailed Description

CAiwServiceHandler is the main class of the Application 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 AIW Framework to use only those providers in which the consumer is interested in. The criteria consists of following attributes:

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.


Public Member Functions
virtual IMPORT_C  ~CAiwServiceHandler ()
  Destructor.
IMPORT_C void  Reset ()
  Resets the Service Handler, discards existing interest and unloads corresponding service providers.
IMPORT_C TInt  NbrOfProviders (const CAiwCriteriaItem *aCriteria)
  Returns the amount of providers that fulfil the given criteria.
IMPORT_C void  AttachL (TInt aInterestResourceId)
  Adds the given interest to the Service Handler from a resource and updates possibly existing old interest.
IMPORT_C void  AttachL (const RCriteriaArray &aInterest)
  Adds given interest to the Service Handler from an array of criteria items.
IMPORT_C void  GetInterest (RCriteriaArray &aInterest)
  Gets the currently valid interest in use by the Service Handler.
IMPORT_C void  DetachL (const RCriteriaArray &aInterest)
  Removes given interest from the Service Handler.
IMPORT_C void  DetachL (TInt aInterestResourceId)
  Removes given interest from the Service Handler.
IMPORT_C const CAiwCriteriaItem *  GetCriteria (TInt aId)
  Returns criteria by ID.
IMPORT_C CAiwGenericParamList &  InParamListL ()
  Returns an empty instance of CAiwGenericParamList class.
IMPORT_C CAiwGenericParamList &  OutParamListL ()
  Returns an empty instance of CAiwGenericParamList class.
IMPORT_C void  InitializeMenuPaneL (CEikMenuPane &aMenuPane, TInt aMenuResourceId, TInt aBaseMenuCmdId, const CAiwGenericParamList &aInParamList)
  Initialises menu pane with service commands from a provider.
IMPORT_C void  InitializeMenuPaneL (CEikMenuPane &aMenuPane, TInt aMenuResourceId, TInt aBaseMenuCmdId, const CAiwGenericParamList &aInParamList, TBool aUseSubmenuTextsIfAvailable)
  Initialises menu pane with service commands from a provider.
IMPORT_C TInt  ServiceCmdByMenuCmd (TInt aMenuCmdId) const
  Returns the service command ID associated to the menu command.
IMPORT_C void  ExecuteMenuCmdL (TInt aMenuCmdId, const CAiwGenericParamList &aInParamList, CAiwGenericParamList &aOutParamList, TUint aCmdOptions=0, MAiwNotifyCallback *aCallback=NULL)
  Tells the provider to execute a menu command invoked by the consumer.
IMPORT_C void  AttachMenuL (TInt aMenuResourceId, TInt aInterestResourceId)
  Attach menu related criteria items to the given menu.
IMPORT_C void  AttachMenuL (TInt aMenuResourceId, TResourceReader &aReader)
  Attach menu related criteria items to the given menu.
IMPORT_C void  AttachMenuL (TInt aMenuResourceId, const RCriteriaArray &aInterest)
  Attach menu related criteria items to the given menu.
IMPORT_C void  DetachMenu (TInt aMenuResourceId, TInt aInterestResourceId)
  Detach menu related criteria items from the given menu.
IMPORT_C TBool  IsSubMenuEmpty (TInt aSubMenuId)
  Checks if there are menu providers attached to given menu id.
IMPORT_C TBool  IsAiwMenu (TInt aMenuResourceId)
  Returns boolean value indicating whether the given menu contains currently attached placeholders.
IMPORT_C TBool  HandleSubmenuL (CEikMenuPane &aPane)
  Handles AIW submenus.
IMPORT_C void  ExecuteServiceCmdL (const TInt &aCmdId, const CAiwGenericParamList &aInParamList, CAiwGenericParamList &aOutParamList, TUint aCmdOptions=0, MAiwNotifyCallback *aCallback=0)
  Executes a service command for all providers.

Static Public Member Functions
static IMPORT_C CAiwServiceHandler *  NewL ()
  Constructs a Service Handler instance.
static IMPORT_C CAiwServiceHandler *  NewLC ()
  Constructs a Service Handler instance.
static IMPORT_C void  ReportMenuLaunch ()
  CEikMenuPane uses this method to inform AIF framework that a menu is launched.

Constructor & Destructor Documentation

virtual IMPORT_C CAiwServiceHandler::~CAiwServiceHandler (   )  [virtual]
 

Destructor.

Member Function Documentation

IMPORT_C void CAiwServiceHandler::AttachL (  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:
aInterest  Array of criteria items. Ownership is not transferred.
IMPORT_C void CAiwServiceHandler::AttachL (  TInt  aInterestResourceId  ) 
 

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.

Parameters:
aInterestResourceId  ID of the resource containing criteria items.
Leave:
KErrNotSupported CCoeEnv is not accessible.
See also:
Reset
IMPORT_C void CAiwServiceHandler::AttachMenuL (  TInt  aMenuResourceId,
const RCriteriaArray &  aInterest
) 
 

Attach menu related criteria items to the given menu.

Parameters:
aMenuResourceId  Menu to be attached.
aInterest  Array of criteria items. Ownership is not transferred.
Leave:
KErrNotSupported CCoeEnv is not accessible.
IMPORT_C void CAiwServiceHandler::AttachMenuL (  TInt  aMenuResourceId,
TResourceReader &  aReader
) 
 

Attach menu related criteria items to the given menu.

If a provider leaves during initialization, it is trapped by the Service Handler.

Parameters:
aMenuResourceId  Menu to be attached.
aReader  Resource reader for the interest list.
Leave:
KErrNotSupported CCoeEnv is not accessible.
IMPORT_C void CAiwServiceHandler::AttachMenuL (  TInt  aMenuResourceId,
TInt  aInterestResourceId
) 
 

Attach menu related criteria items to the given menu.

If a provider leaves during initialization, it is trapped by the Service Handler.

Parameters:
aMenuResourceId  Menu to be attached.
aInterestResourceId  Resource id for the interest list.
Leave:
KErrNotSupported CCoeEnv is not accessible.
IMPORT_C void CAiwServiceHandler::DetachL (  TInt  aInterestResourceId  ) 
 

Removes given interest from the Service Handler.

Corresponding service providers are unloaded.

Parameters:
aInterestResourceId  ID of the resource containing criteria items.
Leave:
KErrNotSupported CCoeEnv is not accessible.
IMPORT_C void CAiwServiceHandler::DetachL (  const RCriteriaArray &  aInterest  ) 
 

Removes given interest from the Service Handler.

Corresponding service providers are unloaded.

Parameters:
aInterest  Array of returned criteria items, may be empty.
IMPORT_C void CAiwServiceHandler::DetachMenu (  TInt  aMenuResourceId,
TInt  aInterestResourceId
) 
 

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:
aMenuResourceId  Menu to be detached.
aInterestResourceId  Resource id for the interest list. If NULL, all criteria items are detached from the given menu.
IMPORT_C void CAiwServiceHandler::ExecuteMenuCmdL (  TInt  aMenuCmdId,
const CAiwGenericParamList &  aInParamList,
CAiwGenericParamList &  aOutParamList,
TUint  aCmdOptions = 0,
MAiwNotifyCallback *  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.

Parameters:
aMenuCmdId  The menu command to be executed.
aInParamList  Input data parameters, can be an empty list.
aOutParamList  Output data parameters, can be an empty list.
aCmdOptions  Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.
aCallback  Callback for asynchronous command handling, parameter checking, etc.
Leave:
KErrArgument Callback is missing when required.
Leave:
KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible.
See also:
ServiceCmdByMenuCmd
IMPORT_C void CAiwServiceHandler::ExecuteServiceCmdL (  const TInt &  aCmdId,
const CAiwGenericParamList &  aInParamList,
CAiwGenericParamList &  aOutParamList,
TUint  aCmdOptions = 0,
MAiwNotifyCallback *  aCallback = 0
) 
 

Executes a service command for all providers.

Otherwise similar to ExecuteMenuCmdL.

Parameters:
aCmdId  The command to be executed.
aInParamList  Input data parameters, can be an empty list.
aOutParamList  Output data parameters, can be an empty list.
aCmdOptions  Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.
aCallback  Callback for asynchronous command handling, parameter checking, etc.
Leave:
KErrArgument Callback is missing when required.
Leave:
KErrNotSupported No provider supports the service.
IMPORT_C const CAiwCriteriaItem* CAiwServiceHandler::GetCriteria (  TInt  aId  ) 
 

Returns criteria by ID.

Parameters:
aId  Criteria ID.
Returns:
Criteria item pointer matching the ID. Ownership is not transferred.
IMPORT_C void CAiwServiceHandler::GetInterest (  RCriteriaArray &  aInterest  ) 
 

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

Parameters:
aInterest  An array of returned criteria items, may be empty. Ownership is not transferred, i.e. the objects in the array must not be deleted.
IMPORT_C TBool CAiwServiceHandler::HandleSubmenuL (  CEikMenuPane &  aPane  ) 
 

Handles AIW submenus.

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

Parameters:
aPane  Menu pane to be handled.
Returns:
ETrue if aPane was an AIW submenu and it was handled. Consumer's DynInitMenuPaneL pane may now return. EFalse if aPane was not an AIW submenu and DynInitMenuPaneL should continue normally.
IMPORT_C void CAiwServiceHandler::InitializeMenuPaneL (  CEikMenuPane &  aMenuPane,
TInt  aMenuResourceId,
TInt  aBaseMenuCmdId,
const CAiwGenericParamList &  aInParamList,
TBool  aUseSubmenuTextsIfAvailable
) 
 

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.

Parameters:
aMenuPane  Handle of the menu pane to initialise.
aMenuResourceId  The menu to be attached.
aBaseMenuCmdId  Base ID for the Service Handler to generate menu IDs for placeholders.
aInParamList  Input parameter list for provider's parameters checking.
aUseSubmenuTextsIfAvailable  If 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 AIW_CASCADE_ID or AIW_INTELLIGENT_CASCADE_ID, the AIW framework can automatically decide whether to use the submenu texts or not, and this parameter has no effect.
Leave:
KErrNotSupported CCoeEnv is not accessible.
Leave:
KErrOverflow Consumer application has too many AIW placeholders in its menu. Currently, maximum 16 is supported.
IMPORT_C void CAiwServiceHandler::InitializeMenuPaneL (  CEikMenuPane &  aMenuPane,
TInt  aMenuResourceId,
TInt  aBaseMenuCmdId,
const CAiwGenericParamList &  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.

Parameters:
aMenuPane  Handle of the menu pane to initialise.
aMenuResourceId  The menu to be attached.
aBaseMenuCmdId  Base ID for the Service Handler to generate menu IDs for placeholders.
aInParamList  Input parameter list for provider's parameters checking.
Leave:
KErrNotSupported CCoeEnv is not accessible.
Leave:
KErrOverflow Consumer application has too many AIW placeholders in its menu. Currently, maximum 16 is supported.
IMPORT_C CAiwGenericParamList& CAiwServiceHandler::InParamListL (   ) 
 

Returns an empty instance of CAiwGenericParamList 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.

Returns:
An empty instance of CAiwGenericParameter list.
IMPORT_C TBool CAiwServiceHandler::IsAiwMenu (  TInt  aMenuResourceId  ) 
 

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

Parameters:
aMenuResourceId  Resource id of the menu to be queried.
Returns:
ETrue if aMenuResource contains currently attached placeholders. EFalse otherwise.
IMPORT_C TBool CAiwServiceHandler::IsSubMenuEmpty (  TInt  aSubMenuId  ) 
 

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 AIW items should be hidden or not.

Parameters:
aSubMenuId  The menu id to be checked.
Returns:
ETrue if there isn't any menu providers attached to this menu. EFalse otherwise.
IMPORT_C TInt CAiwServiceHandler::NbrOfProviders (  const CAiwCriteriaItem *  aCriteria  ) 
 

Returns the amount of providers that fulfil the given criteria.

Parameters:
aCriteria  Criteria to match.
Returns:
Number of providers matching the criteria.
static IMPORT_C CAiwServiceHandler* CAiwServiceHandler::NewL (   )  [static]
 

Constructs a Service Handler instance.

static IMPORT_C CAiwServiceHandler* CAiwServiceHandler::NewLC (   )  [static]
 

Constructs a Service Handler instance.

IMPORT_C CAiwGenericParamList& CAiwServiceHandler::OutParamListL (   ) 
 

Returns an empty instance of CAiwGenericParamList 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.

Returns:
An empty instance of CAiwGenericParameter list.
static IMPORT_C void CAiwServiceHandler::ReportMenuLaunch (   )  [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.

IMPORT_C void CAiwServiceHandler::Reset (   ) 
 

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

IMPORT_C TInt CAiwServiceHandler::ServiceCmdByMenuCmd (  TInt  aMenuCmdId  )  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.

Parameters:
aMenuCmdId  Menu command ID to be mapped to service cmd.
Returns:
Service command ID, KAiwCmdNone if no ID is found.
See also:
ExecuteMenuCmdL
The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2008
Back to top