Symbian^3 Application 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

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]

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 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]

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
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.

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 (only filename).
const TDesC8 & aScript Descriptor containing the script.

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.