Collapse all Symbian^3 Product Developer Library

CCFClient Class Reference

class CCFClient : public CBase

Client side API of Context Framework.

Context Framework Client provides following functionality:

Define contexts
Publish contexts
Subscribe contexts
Define actions
Subscribe actions
Register new scripts
Deregister scripts

Before contexts can be published or subscribed it first needs to be defined. Otherwise error code will be returned to client side.

Before actions can be subscribed they must be defined. Every action must be secured with a security policy. If your action does not need any security, NONE capabilities can be defined.

Client application can request contexts that have been published in Context Framework. Contexts will be delivered in an array. Array will contain all the context objects where the client has sufficient capabilities.

This class is not intended for user derivation.

Below is described is described examples how to utilze Context Framework Client.

Initialize: When CCFClient instance is created a connection to Context Framework Server is also created. Creator of the instance must implement MCFListener interface and pass it as a parameter.

  CCFClient* client = CCFClient::NewLC( *this );
  CleanupStack::PopAndDestroy( client );

Define context: If the context is already been defined it cannot be redfined. KErrAlreadyExists is returned to the client if the context has already been defined. You can use a security policy that is suitable for your own context. Remember not to set bigger capabilities than your process has.

  _LIT( KContextSource, "Source" );
  _LIT( KContextType, "Type" );
  _LIT_SECURITY_POLICY_PASS( KContextSec );
  CCFClient* client = CCFClient::NewLC( *this );
  TInt err = client->DefineContext( KContextSource, KContextType, KContextSec );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( client );

Publish context: Before context can bee published it must have been defined. KErrNotFound is returned to the client if the published context cannot be found. KErrAccessDenied is returned if the client process does not have sufficient capabilities.

  _LIT( KContextSource, "Source" );
  _LIT( KContextType, "Type" );
  _LIT( KContextValue, "Value" );
  CCFContextObject* co = CCFContextObject::NewLC();
  co->SetSourceL( KContextSource );
  co->SetTypeL( KContextType );
  co->SetValueL( KContextValue );
  CCFClient* client = CCFClient::NewLC( *this );
  TInt err = client->PublishContext( *co );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( client );
  CleanupStack::PopAndDestroy( co );

Subscribe context: Context can be subscribed without it being defined. When the client subscribes for a context which has not been defined the context subscription is treated as "unsecure". When the specified context is defined a capability check is done. If the client process does not have sufficient capabilities, an error is notified through MCFListener interface. When the subscribed context changes context indication is notified through MCFListener interface.

  _LIT( KContextSource, "Source" );
  _LIT( KContextType, "Type" );
  _LIT( KContextValue, "Value" );
  CCFClient* client = CCFClient::NewLC( *this );
  CCFContextSubscription* subscription = CCFContextSubscription::NewLC();
  subscription->SetSourceL( KContextSource );
  subscription->SetTypeL( KContextType );
  TInt err = client->SubscribeContext( *subscription );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( subscription );
  CleanupStack::PopAndDestroy( client );

Request context: Only contexts that have been defined can be requested. Since contexts has a certain security a security check is done. If client process does not have sufficient capabilities for the requested context it will not be returned. The request can also contain a set of queries.

  _LIT( KContextSource, "Source" );
  _LIT( KContextType, "Type" );
  CCFContextQuery* query = CCFContextQuery::NewLC();
  query->SetSourceL( KContextSource );
  query->SetTypeL( KContextType );
  CCFClient* client = CCFClient::NewLC( *this );
  RContextObjectArray result;
  TInt err = client->RequestContext( query, result );
  if( err != KErrNone )
  {
      // handle error
  }
  else if( result.Count() )
  {
      // handle result
  }
  result.ResetAndDestroy();
  CleanupStack::PopAndDestroy( client );
  CleanupStack::PopAndDestroy( query );

Define action: Defines an action in Context Framework Server. Only one action with the same identifier can be defined. KErrAlreadyExists is returned if the action is already defined. Action needs a certain security level. A specific security level can be defined for every action that is defined.

  _LIT( KAction, "ActionId" );
  _LIT_SECURITY_POLICY_PASS( KActionSec );
  CCFClient* client = CCFClient::NewLC( *this );
  TInt err = client->DefineAction( KAction, KActionSec );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( client );

Subscribe action: Actions must be defined before they can be subscribed. KErrNotFound is returned if an action is tried to be subscribed without being defined. Client process must have the needed security level for the action. If client process fail security check KErrAccessDenied is returned. When a certain rule is evaluated to true where the subscribed action is executed action indication is notified through MCFListener interface.

  _LIT( KAction, "ActionId" );
  CCFClient* client = CCFClient::NewLC( *this );
  CCFActionSubscription* subscription = CCFActionSubscription::NewLC();
  subscription->SetActionIdentifierL( KAction );
  TInt err = client->SubscribeAction( *subscription );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( subscription );
  CleanupStack::PopAndDestroy( client );

Register script: Client can register own scripts to Context Framework. When the script is registered all the context objects and actions related to the script is evaluated and security check is made. Client process must have sufficient security for the context objects and actions used in the script. The new script is not permanently registered and stored. When the device is rebooted client needs to re-register the script. Notice that the script file must be in public location so that Context Framework server can access to it.

  _LIT( KScriptPath, "c:\\data\\myscripts\\script.rul" );
  CCFClient* client = CCFClient::NewLC( *this );
  TInt ruleId = 0;
  TInt err = client->RegisterScript( KScriptPath, ruleId );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( client );

Deregister script: Before a script can be deregistered it must have been first registered.

  _LIT( KScriptPath, "c:\\data\\myscripts\\script.rul" );
  CCFClient* client = CCFClient::NewLC( *this );
  TInt ruleId = 0;
  TInt err = client->RegisterScript( KScriptPath, ruleId );
  if( err != KErrNone )
  {
      // handle error
  }
  err = client->DeregisterScript( ruleId );
  if( err != KErrNone )
  {
      // handle error
  }
  CleanupStack::PopAndDestroy( client );

CFClient.lib

Since: S60 5.0

Inherits from

CCFClient
- CBase

Public Member Functions
TInt	DefineAction(const TDesC &, const TSecurityPolicy &)
TInt	DefineContext(const TDesC &, const TDesC &, const TSecurityPolicy &)
TInt	DefineContext(const TDesC &, const TDesC &, const TSecurityPolicy &, const TSecurityPolicy &)
TInt	DeleteContextSourceSetting(const TDesC &, const TUid &)
TInt	DeleteContextSourceSettings(const TUid &)
TInt	DeleteScript(const TDesC &)
TInt	DeleteScripts()
TInt	DeregisterScript(TInt)
IMPORT_C CCFClient *	NewL(MCFListener &)
IMPORT_C CCFClient *	NewLC(MCFListener &)
TInt	PublishContext(CCFContextObject &)
TInt	PublishContext(CCFContextObject &, CCFContextDataObject &)
TInt	RegisterScript(const TDesC &, TInt &)
TInt	RegisterScript(const TDesC &, const TDesC8 &, TInt &)
TInt	RequestContext(CCFContextQuery &, RContextObjectArray &)
TInt	RequestContextSet(RContextQueryArray &, RContextObjectArray &)
TInt	RestoreRomScript(const TDesC &)
TInt	SaveContextSourceSetting(const TDesC &, const TUid &)
TInt	SaveScript(const TDesC &, TInt &)
TInt	SaveScript(const TDesC &, const TDesC8 &, TInt &)
TInt	SubscribeAction(CCFActionSubscription &)
TInt	SubscribeContext(CCFContextSubscription &)
TInt	UnsubscribeAction(CCFActionSubscription &)
TInt	UnsubscribeContext(CCFContextSubscription &)
TInt	UpgradeRomScript(const TDesC &)
TInt	UpgradeRomScript(const TDesC &, const TDesC8 &)

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

Member Functions Documentation

DefineAction(const TDesC &, const TSecurityPolicy &)

TInt	DefineAction	(	const TDesC &	aActionIdentifier,
			const TSecurityPolicy &	aSecurityPolicy
		)	[pure virtual]

Defines an action in Context Framework. When action is defined in Context Framework it can be subscribed. When the action is needed to be executed action indication is received through MCFListener interface. Notice that actions can be defined also from action plug-ins. If some action plug-in has already defined the action in hand action definition will fail.

Since: S60 5.0

Parameters

const TDesC & aActionIdentifier	Action identifier.
const TSecurityPolicy & aSecurityPolicy	Security policy for the action.

DefineContext(const TDesC &, const TDesC &, const TSecurityPolicy &)

TInt	DefineContext	(	const TDesC &	aContextSource,
			const TDesC &	aContextType,
			const TSecurityPolicy &	aReadWritePolicy
		)	[pure virtual]

Defines a new context in Context Framework. Every context needs to be defined before it can be published, subscribed or requested.

Security policy for reading and writing is the same.

If some client subscribes for this context, the contex owner will be notified through MCFContextSource interface. MCFContextSource interface will be enquired through MCFListener interface extension.

Since: S60 5.0

Parameters

const TDesC & aContextSource	Source of the context.
const TDesC & aContextType	Type of the context.
const TSecurityPolicy & aReadWritePolicy	Needed capabilities for the context.

DefineContext(const TDesC &, const TDesC &, const TSecurityPolicy &, const TSecurityPolicy &)

TInt	DefineContext	(	const TDesC &	aContextSource,
			const TDesC &	aContextType,
			const TSecurityPolicy &	aReadPolicy,
			const TSecurityPolicy &	aWritePolicy
		)	[pure virtual]

Defines a new context in Context Framework. Every context needs to be defined before it can be published, subscribed or requested.

Security policy for reading and writing are different.

If some client subscribes for this context, the contex owner will be notified through MCFContextSource interface. MCFContextSource interface will be enquired through MCFListener interface extension.

Since: S60 5.0

Parameters

const TDesC & aContextSource	Source of the context.
const TDesC & aContextType	Type of the context.
const TSecurityPolicy & aReadPolicy	Needed capabilities for reading context value.
const TSecurityPolicy & aWritePolicy	Needed capabilities for writing context value.

DeleteContextSourceSetting(const TDesC &, const TUid &)

TInt	DeleteContextSourceSetting	(	const TDesC &	aSettingFilename,
			const TUid &	aContextSourceUid
		)	[pure virtual]

Deletes a context source setting in Context Framework. Setting is removed if uninstall succeeds.

Since: S60 5.0

Parameters

const TDesC & aSettingFilename	Filename (without path) that was used to install the setting.
const TUid & aContextSourceUid	Implementation UID of the context source.

DeleteContextSourceSettings(const TUid &)

TInt

DeleteContextSourceSettings

(

const TUid &

aContextSourceUid

)

[pure virtual]

Uninstalls context source settings registered by a client in Context Framework. Uninstalls all settings ever registered by the client for the context source. Settings are removed if uninstall succeeds.

Since: S60 5.0

Parameters

const TUid & aContextSourceUid

Implementation UID of the context source.

DeleteScript(const TDesC &)

TInt

DeleteScript

(

const TDesC &

aScriptFileName

)

[pure virtual]

Delete a script from Context Framework private folder. The script will be automatically deregistered.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName

DeleteScripts()

TInt

DeleteScripts

(

)

[pure virtual]

Delete all scripts from Context Framework private folder added by the particular process. All the scripts are automatically deregistered.

Since: S60 5.0

DeregisterScript(TInt)

TInt

DeregisterScript

(

TInt

aScriptId

)

[pure virtual]

Deregisters a script in Context Framework.

Since: S60 5.0

Parameters

TInt aScriptId

Script obtained from RegisterScript -method.

NewL(MCFListener &)

IMPORT_C CCFClient *

NewL

(

MCFListener &

aListener

)

[static]

Symbian two phased constructors.

Since: S60 5.0

Parameters

MCFListener & aListener

Context Framework listener interface.

NewLC(MCFListener &)

IMPORT_C CCFClient *

NewLC

(

MCFListener &

aListener

)

[static]

Parameters

MCFListener & aListener

PublishContext(CCFContextObject &)

TInt

PublishContext

(

CCFContextObject &

aContext

)

[pure virtual]

Publishes a new value of a context into Context Framework. Subscribed clients will be notified of the change. Context must have been defined before it can be published.

Since: S60 5.0

Parameters

CCFContextObject & aContext

Context object to be added.

PublishContext(CCFContextObject &, CCFContextDataObject &)

TInt	PublishContext	(	CCFContextObject &	aContext,
			CCFContextDataObject &	aData
		)	[pure virtual]

Publishes a new value of a context into Context Framework. Subscribed clients will be notified of the change. Context can be associated with a specific data object. If a subscriber has requested to receive also data objects the data object is associated in the context indication. Context must have been defined before it can be published.

Since: S60 5.0

Parameters

CCFContextObject & aContext	Context object to be added.
CCFContextDataObject & aData	Data object associated the context.

RegisterScript(const TDesC &, TInt &)

TInt	RegisterScript	(	const TDesC &	aScriptFileName,
			TInt &	aScriptId
		)	[pure virtual]

Registers a new script in Context Framework. If the client process wants to provide the actions defined in the script it is necessary first to subscribe the actions needed and then register the script. If a script with the same name is found, it will be automatically replaced and the script id remains the same.

Notice that the script is valid until the device is rebooted. After reboot, the script is needed to be registered again.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName	File path to the script.
TInt & aScriptId	Script ID return value.

RegisterScript(const TDesC &, const TDesC8 &, TInt &)

TInt	RegisterScript	(	const TDesC &	aScriptFileName,
			const TDesC8 &	aScript,
			TInt &	aScriptId
		)	[pure virtual]

Notice that the script is valid until the device is rebooted. After reboot, the script is needed to be registered again.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName	Name of the script.
const TDesC8 & aScript	Descriptor containing the script.
TInt & aScriptId	Script ID return value.

RequestContext(CCFContextQuery &, RContextObjectArray &)

TInt	RequestContext	(	CCFContextQuery &	aContextQuery,
			RContextObjectArray &	aRequestResults
		)	[pure virtual]

Requests the latest context of the specified type, source, or type & source from the Context Framework. All the contexts where client has enough capabilities will be returned in aRequestResult array.

Since: S60 5.0

Parameters

CCFContextQuery & aContextQuery	Requirements for context type and source. If the given type is a partial ontology path, all contexts beginning with that will be returned. Accordingly, if the given source is a partial source name, all contexts from a source having that beginning will be returned.
RContextObjectArray & aRequestResults	Storage for the requested contexts.

RequestContextSet(RContextQueryArray &, RContextObjectArray &)

TInt	RequestContextSet	(	RContextQueryArray &	aContextQuerySet,
			RContextObjectArray &	aRequestResults
		)	[pure virtual]

Requests the latest context of the specified types, sources, or types & sources from the Context Framework. All the contexts where client has enough capabilities will be returned in aRequestResult array.

Note:

Using partial ontology paths in types or partial source names may result in repeated occurrence of the same contexts (redundancy), as is also the case with repeating exactly the same definition in the query set.

Since: S60 5.0

Parameters

RContextQueryArray & aContextQuerySet

An array of query definitions containing type and source requirement pairs. If the given type is a partial ontology path, all contexts beginning with that will be stored into the provided storage array. Accordingly,if the given source is a partial source name, all contexts from a source having that beginning will also be stored. The given query set does not have to be analogous. One element may define only the type, another only the source, and finally, some other might define both type and source.

RContextObjectArray & aRequestResults

Storage for the requested contexts. The call just returns and leaves this set untouchable, if the given query set is empty.

RestoreRomScript(const TDesC &)

TInt

RestoreRomScript

(

const TDesC &

aScriptFileName

)

[pure virtual]

Restores the script located in ROM. The script upgrade is deregistered and deleted from file system. The original script located in ROM is registered in to use again.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName

Script which to replace (full path).

SaveContextSourceSetting(const TDesC &, const TUid &)

TInt	SaveContextSourceSetting	(	const TDesC &	aSettingFilename,
			const TUid &	aContextSourceUid
		)	[pure virtual]

Saves a context source setting in Context Framework. Setting is stored if install succeeds.

Since: S60 5.0

Parameters

const TDesC & aSettingFilename	Filename with full path to the setting.
const TUid & aContextSourceUid	Implementation UID of the context source to receive setting.

SaveScript(const TDesC &, TInt &)

TInt	SaveScript	(	const TDesC &	aScriptFileName,
			TInt &	aScriptId
		)	[pure virtual]

Saves a new script in Context Framework private folder. The script will be registered and updated when necessary. The script will be automatically loaded on next device boot up. If a script with the same name already exists, it will be automatically replaced.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName	The full path to a script file.
TInt & aScriptId	Script ID return value.

SaveScript(const TDesC &, const TDesC8 &, TInt &)

TInt	SaveScript	(	const TDesC &	aScriptFileName,
			const TDesC8 &	aScript,
			TInt &	aScriptId
		)	[pure virtual]

Since: S60 5.0

Parameters

const TDesC & aScriptFileName
const TDesC8 & aScript	Descriptor containing the script.
TInt & aScriptId	Script ID return value.

SubscribeAction(CCFActionSubscription &)

TInt

SubscribeAction

(

CCFActionSubscription &

aSubscription

)

[pure virtual]

Subscribes for action. When certain action is needed to be performed action indication is informed through MCFListener API. Every action is needed to be defined before they can be subscribed.

Since: S60 5.0

Parameters

CCFActionSubscription & aSubscription

Action subscription

SubscribeContext(CCFContextSubscription &)

TInt

SubscribeContext

(

CCFContextSubscription &

aSubscription

)

[pure virtual]

Add subscription to Context Framework to get indications about context changes of certain type. If client does not have suffcient capabilities error will be informed through MCFListener interface. This can happen if client subscribes in a context that has not yet been defined. When the context is later on defined a check is made against clients process capabilities. If client lacks capabilities error will be notifed.

Since: S60 5.0

Parameters

CCFContextSubscription & aSubscription

Information about which kind of context changes are sent to object implementing MCFListener.

UnsubscribeAction(CCFActionSubscription &)

TInt

UnsubscribeAction

(

CCFActionSubscription &

aSubscription

)

[pure virtual]

Unsubscribes for action.

Since: S60 5.0

Parameters

CCFActionSubscription & aSubscription

Action subscription

UnsubscribeContext(CCFContextSubscription &)

TInt

UnsubscribeContext

(

CCFContextSubscription &

aSubscription

)

[pure virtual]

Remove subscription from context manager. If subscription is not found on the server this method leaves with KErrNotFound.

Since: S60 5.0

Parameters

CCFContextSubscription & aSubscription

Subscription to be removed. This must be the same object that is used in SubscribeL() method.

UpgradeRomScript(const TDesC &)

TInt

UpgradeRomScript

(

const TDesC &

aScriptFileName

)

[pure virtual]

Upgrade existing script in ROM. The new script is saved in C-drive and registered automatically. The script located in ROM is inactive untill the upgrade will be deleted. If a script with the same name is found, it will be automatically replaced.

The client must have the needed capabilities to be able to upgrade rom script. The script which acts as an upgrade must also have at least the same upgrade security level than the original script located in rom.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName

Script which to replace (full path).

UpgradeRomScript(const TDesC &, const TDesC8 &)

TInt	UpgradeRomScript	(	const TDesC &	aScriptFileName,
			const TDesC8 &	aScript
		)	[pure virtual]

Upgrade existing script in ROM. The currently registered ROM based script will be deregistered and the new script will be stored in RAM. The script located in ROM is inactive untill the upgrade will be deleted. If a script with the same name is found, it will be automatically replaced.

Since: S60 5.0

Parameters

const TDesC & aScriptFileName	Script which to replace (only filename).
const TDesC8 & aScript	Descriptor containing the script.