CVwsSessionWrapper Class Reference

class CVwsSessionWrapper : public CBase

The CVwsSessionWrapper class mediates access to the view server client session which it creates, and wraps in support for notification of server events. A session observer will be called back with server events if it maintains an outstanding request for asynchronous event notification.

Inherits from

Public Member Functions
~CVwsSessionWrapper ()
IMPORT_C TInt ActivateView (const TVwsViewId &, TUid , const TDesC8 &)
IMPORT_C void ActivateView (const TVwsViewId &, TUid , const TDesC8 &, TRequestStatus &)
IMPORT_C TInt ActivateView (const TVwsViewId &, TUid , const TDesC8 &, TInt )
IMPORT_C void ActivateView (const TVwsViewId &, TUid , const TDesC8 &, TRequestStatus &, TInt )
IMPORT_C TInt ActivateViewViaViewEvent (const TVwsViewIdAndMessage &)
IMPORT_C TInt AddView (const TVwsViewId &)
IMPORT_C TInt CheckSourceOfViewSwitch ( TBool &, const TSecurityPolicy &, const char *)
IMPORT_C TInt CreateActivateViewEvent (const TVwsViewId &, TUid , const TDesC8 &)
IMPORT_C TInt CreateActivateViewEvent (const TVwsViewId &, TUid , const TDesC8 &, TInt )
IMPORT_C TInt DeactivateActiveView ()
IMPORT_C TInt DeactivateActiveViewIfOwnerMatch ()
IMPORT_C TInt EnableExternalViewSwitches ( TBool )
IMPORT_C TInt EnableServerBlankScreen ( TBool )
IMPORT_C TInt EnableServerEventTimeOut ( TBool )
IMPORT_C TInt GetCurrentActiveViewInSystem ( TVwsViewId &)
IMPORT_C TInt GetSystemDefaultView ( TVwsViewId &)
IMPORT_C CVwsSessionWrapper * NewL ()
IMPORT_C CVwsSessionWrapper * NewL ( MVwsSessionWrapperObserver &)
IMPORT_C CVwsSessionWrapper * NewLC ()
IMPORT_C CVwsSessionWrapper * NewLC ( MVwsSessionWrapperObserver &)
IMPORT_C TInt NotifyNextActivation (const TVwsViewId &)
IMPORT_C TInt NotifyNextActivation ()
IMPORT_C TInt NotifyNextDeactivation (const TVwsViewId &)
IMPORT_C TInt NotifyNextDeactivation ()
IMPORT_C void QueueAsyncRequest ()
IMPORT_C TInt RemoveView (const TVwsViewId &)
IMPORT_C TInt RequestCustomMessage ( TDes8 &)
IMPORT_C TInt SetClientRequestTimeOut ( TTimeIntervalMicroSeconds32 )
IMPORT_C TInt SetCrossCheckUid (const TUid &)
IMPORT_C TInt SetDefaultView (const TVwsViewId &, TInt )
IMPORT_C TInt SetDefaultView (const TVwsViewId &)
IMPORT_C TInt SetServerEventTimeOut ( TTimeIntervalMicroSeconds32 )
IMPORT_C TInt SetSystemDefaultView (const TVwsViewId &, TInt )
IMPORT_C TInt SetSystemDefaultView (const TVwsViewId &)
IMPORT_C TInt SetWindowBackgroundColor (const TRgb &)
IMPORT_C TInt ShutdownViewServer ()
IMPORT_C TInt StartApp ( TUid )
IMPORT_C TInt StartViewServer ( MVwsAppStarter &)
Private Member Functions
CVwsSessionWrapper ()
CVwsSessionWrapper ( MVwsSessionWrapperObserver &)
TInt CheckCreateViewServerSession ()
void ConstructL ()
TBool IsSchedulerRunning ()
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
MVwsSessionWrapperObserver * iObserver
CVwsSessionEventHandler * iViewEventHandler
RVwsSession * iVwsSession

Constructor & Destructor Documentation

CVwsSessionWrapper()

CVwsSessionWrapper ( ) [private]

CVwsSessionWrapper(MVwsSessionWrapperObserver &)

CVwsSessionWrapper ( MVwsSessionWrapperObserver & aObserver ) [private]

Parameters

MVwsSessionWrapperObserver & aObserver

~CVwsSessionWrapper()

IMPORT_C ~CVwsSessionWrapper ( )

Member Functions Documentation

ActivateView(const TVwsViewId &, TUid, const TDesC8 &)

IMPORT_C TInt ActivateView ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage
)

Activates a view.

Supplies the narrow message text descriptor aCustomMessage for the message type identified by aCustomMessageId to the server.

Establishes a connection to the view server if necessary. Starts the application which owns the view if necessary.

Once a new view is activated the current view is deactivated and the new view is marked as current.

If this thread has an active environment the method returns when view activation completes. Otherwise the method returns immediately after creating an activation event in the view server.

Parameters

const TVwsViewId & aViewId The view to activate
TUid aCustomMessageId The message type being passed in aCustomMessage.
const TDesC8 & aCustomMessage A custom message for the view being activated.

ActivateView(const TVwsViewId &, TUid, const TDesC8 &, TRequestStatus &)

IMPORT_C void ActivateView ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage,
TRequestStatus & aStatus
)

Activates a view asynchronously.

Supplies the narrow message text descriptor aCustomMessage for the message type identified by aCustomMessageId to the server.

Establishes a connection to the view server if necessary. Starts the application which owns the view if necessary.

Once a new view is activated the current view is deactivated and the new view is marked as current.

This function will return immediately

Parameters

const TVwsViewId & aViewId The view to activate
TUid aCustomMessageId The message type being passed in aCustomMessage.
const TDesC8 & aCustomMessage A custom message for the view being activated.
TRequestStatus & aStatus A TRequestStatus for the view activation. The request will be completed when the the view has been activated or when the view activation has failed.

ActivateView(const TVwsViewId &, TUid, const TDesC8 &, TInt)

IMPORT_C TInt ActivateView ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage,
TInt aCustomControl
)

Parameters

const TVwsViewId & aViewId
TUid aCustomMessageId
const TDesC8 & aCustomMessage
TInt aCustomControl

ActivateView(const TVwsViewId &, TUid, const TDesC8 &, TRequestStatus &, TInt)

IMPORT_C void ActivateView ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage,
TRequestStatus & aStatus,
TInt aCustomControl
)

Parameters

const TVwsViewId & aViewId
TUid aCustomMessageId
const TDesC8 & aCustomMessage
TRequestStatus & aStatus
TInt aCustomControl

ActivateViewViaViewEvent(const TVwsViewIdAndMessage &)

IMPORT_C TInt ActivateViewViaViewEvent ( const TVwsViewIdAndMessage & aViewIdAndMessage )

Activates the view identified in aViewIdAndMessage on the next queue of the session's view event handler. This activation path should be used for activation requests that come via view events.

For example, a screen device change will generate a view event in the active view. The active view is then responsible for choosing the next view to activate. Using this activation path ensures that the view activation is processed immediately by the server.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewIdAndMessage & aViewIdAndMessage An object encapsulating the view to activate and the message to be passed to it with the activation event

AddView(const TVwsViewId &)

IMPORT_C TInt AddView ( const TVwsViewId & aViewId )

Adds the view to the list maintained by the view server.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to be added to the view server's list.

CheckCreateViewServerSession()

TInt CheckCreateViewServerSession ( ) [private]

CheckSourceOfViewSwitch(TBool &, const TSecurityPolicy &, const char *)

IMPORT_C TInt CheckSourceOfViewSwitch ( TBool & aResult,
const TSecurityPolicy & aSecurityPolicy,
const char * aDiagnostic
)

Tests whether the thread that requested the current view switch satisfies a security policy. This function can only be called from the thread of the session that owns the view being activated, and only during the activation of a view.

Establishes a connection to the view server if necessary.

CCoeAppUi::CheckSourceOfViewSwitchL

Parameters

TBool & aResult If the requesting thread satisfies the security policy, aResult will be set to ETrue, otherwise it will be set to EFalse. If this function does not complete successfully, aResult is undefined.
const TSecurityPolicy & aSecurityPolicy The security policy to check the requesting thread against.
const char * aDiagnostic

ConstructL()

void ConstructL ( ) [private]

CreateActivateViewEvent(const TVwsViewId &, TUid, const TDesC8 &)

IMPORT_C TInt CreateActivateViewEvent ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage
)

Creates an event to be processed to activate the view identified by aViewId and returns without waiting for the activation to complete. Passes the view the message text descriptor aCustomMessage for a message of type aCustomMessageId.

Note that this method may return without error but the activation may subsequently fail.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to activate
TUid aCustomMessageId The message type being passed in aCustomMessage.
const TDesC8 & aCustomMessage A custom message for the view being activated.

CreateActivateViewEvent(const TVwsViewId &, TUid, const TDesC8 &, TInt)

IMPORT_C TInt CreateActivateViewEvent ( const TVwsViewId & aViewId,
TUid aCustomMessageId,
const TDesC8 & aCustomMessage,
TInt aCustomControl
)

Parameters

const TVwsViewId & aViewId
TUid aCustomMessageId
const TDesC8 & aCustomMessage
TInt aCustomControl

DeactivateActiveView()

IMPORT_C TInt DeactivateActiveView ( )

Note: DeactivateActiveViewIfOwnerMatch should be used instead of this function where it is appropriate.

Deactivates the active view. This is required before exiting an application with an active view.

Establishes a connection to the view server if necessary.

If this thread has an active environment the method returns when view deactivation completes. Otherwise the method returns immediately after creating a deactivation event in the view server.

CVwsSessionWrapper::DeactivateActiveViewIfOwnerMatch

DeactivateActiveViewIfOwnerMatch()

IMPORT_C TInt DeactivateActiveViewIfOwnerMatch ( )

Deactivates the active view, but only if the active view is owned by this session. This is required before exiting an application with an active view.

Establishes a connection to the view server if necessary.

If this thread has an active environment the method returns when view deactivation completes. Otherwise the method returns immediately after creating a deactivation event in the view server.

EnableExternalViewSwitches(TBool)

IMPORT_C TInt EnableExternalViewSwitches ( TBool aEnable )

Enable or disable protection from external view switches for this session.

Views owned by protected sessions can only be activated by view activation requests originating from the same session. Activation requests originating from other sessions will cause a second instance of the application providing the requested view to be started. By default, sessions are not protected from external view switches.

Establishes a connection to the view server if necessary.

Parameters

TBool aEnable If set to ETrue, this session's views will be protected from external view switches. If set to EFalse, they will have no such protection.

EnableServerBlankScreen(TBool)

IMPORT_C TInt EnableServerBlankScreen ( TBool aEnable )

Enables or disables screen blanking between screen device changes.

If screen blanking is enabled, the screen will be covered by a solid window. The color of this blanking window would be as set in CVwsSessionWrapper::SetWindowBackgroundColor method if its used, otherwise by default the color would be solid-white. CVwsSessionWrapper::SetWindowBackgroundColor Establishes a connection to the view server if necessary.

Parameters

TBool aEnable If aEnable is set to ETrue, screen blanking will take place as described above, if aEnable is set to EFalse, screen blanking will not happen.

EnableServerEventTimeOut(TBool)

IMPORT_C TInt EnableServerEventTimeOut ( TBool aEnable )

Enables or disables the server event time out.

This may be called, for example, when debugging on target hardware since server event processing can be interrupted indefinitely by the debugger.

Establishes a connection to the view server if necessary.

Since
App-Framework_6.1

Parameters

TBool aEnable The timeout is enabled if aEnable is set to ETrue, and disabled if aEnable is set to EFalse

GetCurrentActiveViewInSystem(TVwsViewId &)

IMPORT_C TInt GetCurrentActiveViewInSystem ( TVwsViewId & aActiveViewId )

Parameters

TVwsViewId & aActiveViewId

GetSystemDefaultView(TVwsViewId &)

IMPORT_C TInt GetSystemDefaultView ( TVwsViewId & aViewId )

Gets the system default view for the current screen device mode

Parameters

TVwsViewId & aViewId The ViewId of the system default view will be returned in this paramater.

IsSchedulerRunning()

TBool IsSchedulerRunning ( ) [private]

NewL()

IMPORT_C CVwsSessionWrapper * NewL ( ) [static]

Creates a new CVwsSessionWrapper object.

The object returned by this function cannot be used to add new views or request notification of view activations or deactivations. To create an instance without these limitations, an MVwsSessionWrapperObserver must be specified.

NewL(MVwsSessionWrapperObserver &)

IMPORT_C CVwsSessionWrapper * NewL ( MVwsSessionWrapperObserver & aObserver ) [static]

Creates a new CVwsSessionWrapper object.

Parameters

MVwsSessionWrapperObserver & aObserver An implementation of MVwsSessionWrapperObserver. The session observer should handle server events such as view activation/deactivation requests for views owned by this session and notifications of view activations/deactivations that have been requested.

NewLC()

IMPORT_C CVwsSessionWrapper * NewLC ( ) [static]

Creates a new CVwsSessionWrapper object, leaving it on the cleanup stack

The object returned by this function cannot be used to add new views or request notification of view activations or deactivations. To create an instance without these limitations, an MVwsSessionWrapperObserver must be specified.

NewLC(MVwsSessionWrapperObserver &)

IMPORT_C CVwsSessionWrapper * NewLC ( MVwsSessionWrapperObserver & aObserver ) [static]

Creates a new CVwsSessionWrapper object, leaving it on the cleanup stack.

Parameters

MVwsSessionWrapperObserver & aObserver An implementation of MVwsSessionWrapperObserver. The session observer should handle server events such as view activation/deactivation requests for views owned by this session and notifications of view activations/deactivations that have been requested.

NotifyNextActivation(const TVwsViewId &)

IMPORT_C TInt NotifyNextActivation ( const TVwsViewId & aViewId )

Requests that the next activation of the view identified by aViewId be notified to this session. The request is cleared after the next notification. Only the last made notification request is honoured.

This allows any client to track the system current active state.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to monitor for activation.

NotifyNextActivation()

IMPORT_C TInt NotifyNextActivation ( )

Requests that the next activation of any view be notified to this session. The request is cleared after the next notification. Only the last made notification request is honoured.

Establishes a connection to the view server if necessary.

NotifyNextDeactivation(const TVwsViewId &)

IMPORT_C TInt NotifyNextDeactivation ( const TVwsViewId & aViewId )

Requests that the next deactivation of the view identified by aViewId be notified to this session. The request is cleared after the next notification. Only the last made notification request is honoured.

For example, can be used when a screensaver view is deactivated by new user activity to reset the system state.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to monitor for deactivation.

NotifyNextDeactivation()

IMPORT_C TInt NotifyNextDeactivation ( )

Requests that the next deactivation of any view be notified to this session. The request is cleared after the next notification. Only the last made notification request is honoured.

Establishes a connection to the view server if necessary.

QueueAsyncRequest()

IMPORT_C void QueueAsyncRequest ( )

Queues an asynchronous view server event request. This method should be called by the active scheduler so that an outstanding request for view server event notification is maintained. The view server interprets the first queue made by a session as the sign that the session application is up and runnning.

This method is now deprecated becasue the requests are now automatically queued by CVwsSessionWrapper .

RemoveView(const TVwsViewId &)

IMPORT_C TInt RemoveView ( const TVwsViewId & aViewId ) const

Removes a view from the list maintained by the view server.

panic
USER 0 if a connection to the view server has not previously been established.

Parameters

const TVwsViewId & aViewId The view to be removed from the view server's list.

RequestCustomMessage(TDes8 &)

IMPORT_C TInt RequestCustomMessage ( TDes8 & aMessageBufPtr ) const

Retrives the custom message contents for the event currently being processsed from the server.

This method is typically called when the MVwsSessionObserver is notified that it should activate a new view.

panic
USER 0 If a connection to the view server has not previously been established

Parameters

TDes8 & aMessageBufPtr The narrow descriptor for the custom message contents to be written to.

SetClientRequestTimeOut(TTimeIntervalMicroSeconds32)

IMPORT_C TInt SetClientRequestTimeOut ( TTimeIntervalMicroSeconds32 aDuration )

Sets the time out duration for client requests.

If the time taken to process a view event exceeds this limit any outstanding client request will silently be completed.

Establishes a connection to the view server if necessary.

Since
App-Framework_6.1

Parameters

TTimeIntervalMicroSeconds32 aDuration The duration of the timeout, in microseconds.

SetCrossCheckUid(const TUid &)

IMPORT_C TInt SetCrossCheckUid ( const TUid & aCrossCheckUid )

Parameters

const TUid & aCrossCheckUid

SetDefaultView(const TVwsViewId &, TInt)

IMPORT_C TInt SetDefaultView ( const TVwsViewId & aViewId,
TInt aMode
) const

Sets the session default view for the screen device mode aMode to aViewId. Valid values for aMode are those listed in the Wserv initialisation file.

As of R6 this function has no effect.

Parameters

const TVwsViewId & aViewId
TInt aMode

SetDefaultView(const TVwsViewId &)

IMPORT_C TInt SetDefaultView ( const TVwsViewId & aViewId ) const

Overloaded member funtion that sets the session default view for the default screen device mode to aViewId.

As of R6 this funtion has no effect.

Parameters

const TVwsViewId & aViewId

SetServerEventTimeOut(TTimeIntervalMicroSeconds32)

IMPORT_C TInt SetServerEventTimeOut ( TTimeIntervalMicroSeconds32 aDuration )

Sets the time out duration for server events.

If the time taken to process a view event exceeds this limit the server event will be completed. If a client is preventing the view event from completing the server will panic that client.

Establishes a connection to the view server if necessary.

Since
App-Framework_6.1

Parameters

TTimeIntervalMicroSeconds32 aDuration The duration of the timeout, in microseconds.

SetSystemDefaultView(const TVwsViewId &, TInt)

IMPORT_C TInt SetSystemDefaultView ( const TVwsViewId & aViewId,
TInt aMode
)

Sets the system default view for a specific screen device mode.

The system default view is the view used when an unrecoverable error in view activation occurs or when an application exits.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to use as the system default view in the specified screen device mode
TInt aMode The screen device mode that should use aViewId as the system default view. Valid values for aMode are those listed in the Wserv initialization file.

SetSystemDefaultView(const TVwsViewId &)

IMPORT_C TInt SetSystemDefaultView ( const TVwsViewId & aViewId )

Sets the system default view for the default screen device mode.

Establishes a connection to the view server if necessary.

Parameters

const TVwsViewId & aViewId The view to use as the system default view in the default screen device mode

SetWindowBackgroundColor(const TRgb &)

IMPORT_C TInt SetWindowBackgroundColor ( const TRgb & aBgColor )

Parameters

const TRgb & aBgColor

ShutdownViewServer()

IMPORT_C TInt ShutdownViewServer ( )

Shut down the view server.

Establishes a connection to the view server if necessary.

StartApp(TUid)

IMPORT_C TInt StartApp ( TUid aAppToStart )

Starts the application with Uid aAppToStart.

Establishes a connection to the view server if necessary.

The request is queued in the server and processed in turn. The application will be started by a call to the implementation of the MVwsAppStarter interface that is provided at server start up.

This method provides an alternative to apparc for starting apps on systems where use of the view server is preferred to use of the apparc server.

Parameters

TUid aAppToStart The Uid of the app that should be started.

StartViewServer(MVwsAppStarter &)

IMPORT_C TInt StartViewServer ( MVwsAppStarter & aAppStarter ) [static]

Starts the view server, spawning a new thread in which the server will run.

Takes a reference to the implementation of the MVwsAppStarter interface aAppStarter which it will share from the heap and which should be for the exclusive use of the view server only.

Parameters

MVwsAppStarter & aAppStarter

Member Data Documentation

MVwsSessionWrapperObserver * iObserver

MVwsSessionWrapperObserver * iObserver [private]

CVwsSessionEventHandler * iViewEventHandler

CVwsSessionEventHandler * iViewEventHandler [private]

RVwsSession * iVwsSession

RVwsSession * iVwsSession [private]