Collapse all Symbian^3 Product Developer Library

CHsContentPublisher Class Reference

class CHsContentPublisher : public CBase

ECom plug-in interface that Homescreen plug-ins must implement. It is used to control plug-in life cycle: load/destroy plug-ins; suspend/resume plug-in execution.

Since: S60 5.2

Inherits from

CHsContentPublisher
- CBase

Public Member Functions
	~CHsContentPublisher()
void	ConfigureL(RAiSettingsItemArray &)
TAny *	Extension(TUid)
TAny *	GetProperty(TProperty)
void	HandleEvent(TInt, const TDesC &)
void	HandleEvent(const TDesC &, const TDesC &)
TBool	HasMenuItem(const TDesC &)
CHsContentPublisher *	NewL(const THsPublisherInfo &)
const THsPublisherInfo &	PublisherInfo()
void	Resume(TResumeReason)
void	SetOffline()
void	SetOnline()
void	SetProperty(TProperty, TAny *)
void	Start(TStartReason)
void	Stop(TStopReason)
void	SubscribeL(MAiContentObserver &)
void	Suspend(TSuspendReason)

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()

Public Member Enumerations
enum	TProperty { EPublisherContent = 1, EPublisherResources, EPublisherEvents, EContentRequest, EResourceRequest, EPluginName, ECpsCmdBuffer }
enum	TResumeReason { EForeground = 1 }
enum	TStartReason { ESystemStartup = 1, EPageStartup, EPluginStartup }
enum	TStopReason { ESystemShutdown = 1, EPageShutdown, EPluginShutdown }
enum	TSuspendReason { EBackground = 1, EBackupRestore, EGeneralThemeChange }

Private Attributes
TUid	iDestructKey
THsPublisherInfo	iPublisherInfo

Constructor & Destructor Documentation

~CHsContentPublisher()

~CHsContentPublisher

(

)

[inline]

Destroys instance of the plug-in. Called by the framework during plug-in destruction phase.

Member Functions Documentation

ConfigureL(RAiSettingsItemArray &)

void

ConfigureL

(

RAiSettingsItemArray &

aSettings

)

[pure virtual]

Configures the plug-in.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin has set its state according to relevant settings.

Short example how to read plugin settings.

 for( TInt i = 0; i < aSettings.Count(); ++i )
     {
     MAiPluginSettingsItem& item = (aSettings[i])->AiPluginSettingsItem();
     TInt32 value = 0;
     if( ParseInt( value, item.Value() ) != KErrNone )
         {
         continue;
         }
     if( value < 0 )
         {
         continue; // All our settings are counts, skip bad settings
         }
     if( item.Key() == EMySettingMaxUsers )
         {
         iEngine->SetMaxUsers( value );
         continue;
         }
     else if( item.Key() == EMySettingNumItems )
         {
         iNumItems = value;
         continue;
         }
     }
 // aSettings ownership is passed to the plug-in, destroy array.
 aSettings.ResetAndDestroy();

Parameters

RAiSettingsItemArray & aSettings

setting items defined in the UI definition. This plugin takes ownership of the MAiPluginSettings objects in the array. If this method leaves the caller will handle the cleanup.

Extension(TUid)

TAny *

Extension

(

TUid

aUid

)

[inline, virtual]

Returns interface extension. In S60 5.2 extensions are not provided.

Example on how to properly return an extension.

 return NULL; // Requested extension not supported

Parameters

TUid aUid

- UID of the extension interface to access.

GetProperty(TProperty)

TAny *

GetProperty

(

TProperty

aProperty

)

[inline, virtual]

Gets property value.

Since: S60 5.2

TProperty.An example of getting a property

 void CMyPlugin::ConstructL()
     {     
     iContent = AiUtility::CreateContentItemArrayIteratorL( KMyPluginContent );
     iResources = AiUtility::CreateContentItemArrayIteratorL( KMyPluginResources );
     iEvents = AiUtility::CreateContentItemArrayIteratorL( KMyPluginEvents );
     }

 TAny* CMyPlugin::GetPropertyL( TProperty aProperty )
     {
     switch( aProperty )
         {
         case EPublisherContent:
             return iContent;
 
         case EPublisherResources:
             return iResources;
 
         case EPublisherEvents:
             return iEvents;
         }
     return NULL;
     }

Parameters

TProperty aProperty

- identification of property.

HandleEvent(TInt, const TDesC &)

void	HandleEvent	(	TInt	aEvent,
			const TDesC &	aParam
		)	[inline, virtual]

Invoked by the framework when the plug-in must handle an event.

Since: S60 5.2

Parameters

TInt aEvent	- unique identifier of event from plug-in content model.
const TDesC & aParam	- parameters associated with event. Each UI Definition declares events in the format: <event name>="">(<event params>="">), where <event name>=""> is mapped by the framework to unique identifier supplied in aEvent, <event params>=""> are provided to plug-in as-is in the descriptor.

HandleEvent(const TDesC &, const TDesC &)

void	HandleEvent	(	const TDesC &	aEventName,
			const TDesC &	aParam
		)	[inline, virtual]

Invoked by the framework when the plug-in must handle an event.

Since: S60 5.2

Parameters

const TDesC & aEventName	- name of the event from plug-in content model.
const TDesC & aParam	- parameters associated with event. Each UI Definition declares events in the format: <event name>="">(<event params>="">), where <event name>=""> mapping to unique identifier supplied by event is failed by the frame work then the <event name>=""> and <event params>=""> are provied to plug-in as-is in the descriptor.

HasMenuItem(const TDesC &)

TBool

HasMenuItem

(

const TDesC &

aMenuItem

)

[inline, virtual]

Invoked by the framework to query whether the plug-in has a menu item.

Since: S60 5.2

Parameters

const TDesC & aMenuItem

menu item name

NewL(const THsPublisherInfo &)

CHsContentPublisher *

NewL

(

const THsPublisherInfo &

aPublisherInfo

)

[static, inline]

Creates a new plug-in instance based on implementation UID.

Pre-condition: Interface implementation exists by uid aImpUid.

Parameters

const THsPublisherInfo & aPublisherInfo

This plug-in's publisher info.

PublisherInfo()

const THsPublisherInfo &

PublisherInfo

(

)

const [inline]

Gets plug-in's publisher info.

Since: S60 5.2

Resume(TResumeReason)

void

Resume

(

TResumeReason

aReason

)

[pure virtual]

This method transits the plug-in into "Alive" state.

In this state the plug-in is allowed to actively publish data to its observers, and it can consume memory and CPU resources.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin is in "Alive" state and actively publishes its data.

Short example what a typical resume implementation does.

 if( !MyEngineCreated() )
      {
      CreateEngine();
      StartEngine();
      }
  else
      {
      // Publish only changed data!
      RefreshData();
      }

Parameters

TResumeReason aReason

reason for state change, see TResumeReason.

SetOffline()

void

SetOffline

(

)

[inline, virtual]

This method transits the plug-in into "Offline" sub-state. In this state plugin is not allowed to use network connections.

Since: S60 5.2

SetOnline()

void

SetOnline

(

)

[inline, virtual]

This method transits the plug-in into "Online" sub-state. In this state plugin is allowed to use network connections.

Since: S60 5.2

SetProperty(TProperty, TAny *)

void	SetProperty	(	TProperty	aProperty,
			TAny *	aAny
		)	[inline, virtual]

Sets property value.

Since: S60 5.2

TProperty.An example of setting a property

 void CMyPlugin::SetPropertyL( TInt TProperty, TAny* aValue )
     {
     if( !aValue ) 
         {
         return;
         }

     // Save the property here to a member variable
     }

Parameters

TProperty aProperty	- identification of property.
TAny * aAny

Start(TStartReason)

void

Start

(

TStartReason

aReason

)

[pure virtual]

This method transits the plug-in into "Idle" state. Parameter aReason explains the plug-in's startup reason. Based on THsStartReason plug-in may decide its startup behavior.

This method is called by the framework after plugin is constructed and configured.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin is in Idle state.

Parameters

TStartReason aReason

startup reason, see TStartReason.

Stop(TStopReason)

void

Stop

(

TStopReason

aReason

)

[pure virtual]

This method transits the plug-in into its final state. Parameter aReason explains the plug-in's shutdwon reason. Based on THsStopReason plug-in may prepare itself for next startup.

This method is called by the framework before plugin is destroyed.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin is ready to be destroyed.

Parameters

TStopReason aReason

reason for state change, see TStopReason.

SubscribeL(MAiContentObserver &)

void

SubscribeL

(

MAiContentObserver &

aObserver

)

[pure virtual]

Adds the content observer / subscriber to the plug-in. The plug-in must maintain a registry of subscribers and publish data to all of them when new content is available in "Alive" state.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin publishes its data to the subscribed observer.

Short example what a typical subscribe implementation does and one alternative how observers are used.

 if( !ObserverAlreadyAdded( aObserver ) )
     {
     iMyContentObservers.AppendL( aObserver );
     }

 ...

 // Engine reports data changed in "Alive" state

 const TDesC& data = iEngine->LatestData();
 for( TInt i = 0; i < iMyContentObservers.Count(); ++i )
     {
     iMyContentObservers[i].Publish( data );
     }

Parameters

MAiContentObserver & aObserver

content observer to register.

Suspend(TSuspendReason)

void

Suspend

(

TSuspendReason

aReason

)

[pure virtual]

This method transits the plug-in into "Suspended" state.

In this state the plug-in is not allowed to publish data to its observers. CPU resource usage must be minimal, e.g. timers must be stopped, outstanding asynchronous operations must be canceled, etc.

Since: S60 5.2

Pre-condition: None

Post-condition: Plugin suspends publishing data and free resources (timers etc).

Short example what a typical suspend implementation does.

 SuspendEngine();

Parameters

TSuspendReason aReason

reason for state change, see TSuspendReason.

Member Enumerations Documentation

Enum TProperty

CHsContentPublisher properties.

Since: S60 5.2

CHsContentPublisher::SetProperty() CHsContentPublisher::GetProperty()

Enumerators

EPublisherContent = 1	Enables read-only access to iterator of content selectors. GetProperty must return instance of MAiContentItemIterator for content selectors.
EPublisherResources	Enables read-only access to iterator of content references. GetProperty must return instance of MAiContentItemIterator for content references.
EPublisherEvents	Enables read-only access to iterator of events supported by plug-in. GetProperty must return instance of MAiContentItemIterator for events.
EContentRequest	Provides access to MAiContentRequest interface for refreshing a content item. EPublisherContent
EResourceRequest	Provides access to MAiContentRequest interface for refreshing a resource item. EPublisherResources
EPluginName	Provides access to localized plugin name if supported. HBufC* EPublisherResources
ECpsCmdBuffer	Provides access to CPS command buffer.