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 TIntActivateView(const TVwsViewId &, TUid, const TDesC8 &)
IMPORT_C voidActivateView(const TVwsViewId &, TUid, const TDesC8 &, TRequestStatus &)
IMPORT_C TIntActivateView(const TVwsViewId &, TUid, const TDesC8 &, TInt)
IMPORT_C voidActivateView(const TVwsViewId &, TUid, const TDesC8 &, TRequestStatus &, TInt)
IMPORT_C TIntActivateViewViaViewEvent(const TVwsViewIdAndMessage &)
IMPORT_C TIntAddView(const TVwsViewId &)
IMPORT_C TIntCheckSourceOfViewSwitch(TBool &, const TSecurityPolicy &, const char *)
IMPORT_C TIntCreateActivateViewEvent(const TVwsViewId &, TUid, const TDesC8 &)
IMPORT_C TIntCreateActivateViewEvent(const TVwsViewId &, TUid, const TDesC8 &, TInt)
IMPORT_C TIntDeactivateActiveView()
IMPORT_C TIntDeactivateActiveViewIfOwnerMatch()
IMPORT_C TIntEnableExternalViewSwitches(TBool)
IMPORT_C TIntEnableServerBlankScreen(TBool)
IMPORT_C TIntEnableServerEventTimeOut(TBool)
IMPORT_C TIntGetCurrentActiveViewInSystem(TVwsViewId &)
IMPORT_C TIntGetSystemDefaultView(TVwsViewId &)
IMPORT_C CVwsSessionWrapper *NewL()
IMPORT_C CVwsSessionWrapper *NewL(MVwsSessionWrapperObserver &)
IMPORT_C CVwsSessionWrapper *NewLC()
IMPORT_C CVwsSessionWrapper *NewLC(MVwsSessionWrapperObserver &)
IMPORT_C TIntNotifyNextActivation(const TVwsViewId &)
IMPORT_C TIntNotifyNextActivation()
IMPORT_C TIntNotifyNextDeactivation(const TVwsViewId &)
IMPORT_C TIntNotifyNextDeactivation()
IMPORT_C voidQueueAsyncRequest()
IMPORT_C TIntRemoveView(const TVwsViewId &)
IMPORT_C TIntRequestCustomMessage(TDes8 &)
IMPORT_C TIntSetClientRequestTimeOut(TTimeIntervalMicroSeconds32)
IMPORT_C TIntSetCrossCheckUid(const TUid &)
IMPORT_C TIntSetDefaultView(const TVwsViewId &, TInt)
IMPORT_C TIntSetDefaultView(const TVwsViewId &)
IMPORT_C TIntSetServerEventTimeOut(TTimeIntervalMicroSeconds32)
IMPORT_C TIntSetSystemDefaultView(const TVwsViewId &, TInt)
IMPORT_C TIntSetSystemDefaultView(const TVwsViewId &)
IMPORT_C TIntSetWindowBackgroundColor(const TRgb &)
IMPORT_C TIntShutdownViewServer()
IMPORT_C TIntStartApp(TUid)
IMPORT_C TIntStartViewServer(MVwsAppStarter &)
Private Member Functions
CVwsSessionWrapper()
CVwsSessionWrapper(MVwsSessionWrapperObserver &)
TInt CheckCreateViewServerSession()
voidConstructL()
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 TIntActivateView(const TVwsViewId &aViewId,
TUidaCustomMessageId,
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 & aViewIdThe view to activate
TUid aCustomMessageIdThe message type being passed in aCustomMessage.
const TDesC8 & aCustomMessageA custom message for the view being activated.

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

IMPORT_C voidActivateView(const TVwsViewId &aViewId,
TUidaCustomMessageId,
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 & aViewIdThe view to activate
TUid aCustomMessageIdThe message type being passed in aCustomMessage.
const TDesC8 & aCustomMessageA custom message for the view being activated.
TRequestStatus & aStatusA 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 TIntActivateView(const TVwsViewId &aViewId,
TUidaCustomMessageId,
const TDesC8 &aCustomMessage,
TIntaCustomControl
)

Parameters

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

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

IMPORT_C voidActivateView(const TVwsViewId &aViewId,
TUidaCustomMessageId,
const TDesC8 &aCustomMessage,
TRequestStatus &aStatus,
TIntaCustomControl
)

Parameters

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

ActivateViewViaViewEvent(const TVwsViewIdAndMessage &)

IMPORT_C TIntActivateViewViaViewEvent(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 & aViewIdAndMessageAn object encapsulating the view to activate and the message to be passed to it with the activation event

AddView(const TVwsViewId &)

IMPORT_C TIntAddView(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 & aViewIdThe view to be added to the view server's list.

CheckCreateViewServerSession()

TInt CheckCreateViewServerSession()[private]

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

IMPORT_C TIntCheckSourceOfViewSwitch(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 & aResultIf 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 & aSecurityPolicyThe security policy to check the requesting thread against.
const char * aDiagnostic

ConstructL()

voidConstructL()[private]

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

IMPORT_C TIntCreateActivateViewEvent(const TVwsViewId &aViewId,
TUidaCustomMessageId,
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 & aViewIdThe view to activate
TUid aCustomMessageIdThe message type being passed in aCustomMessage.
const TDesC8 & aCustomMessageA custom message for the view being activated.

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

IMPORT_C TIntCreateActivateViewEvent(const TVwsViewId &aViewId,
TUidaCustomMessageId,
const TDesC8 &aCustomMessage,
TIntaCustomControl
)

Parameters

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

DeactivateActiveView()

IMPORT_C TIntDeactivateActiveView()

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

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

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 aEnableIf 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 TIntEnableServerBlankScreen(TBoolaEnable)

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::SetWindowBackgroundColorEstablishes a connection to the view server if necessary.

Parameters

TBool aEnableIf 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 TIntEnableServerEventTimeOut(TBoolaEnable)

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 aEnableThe timeout is enabled if aEnable is set to ETrue, and disabled if aEnable is set to EFalse

GetCurrentActiveViewInSystem(TVwsViewId &)

IMPORT_C TIntGetCurrentActiveViewInSystem(TVwsViewId &aActiveViewId)

Parameters

TVwsViewId & aActiveViewId

GetSystemDefaultView(TVwsViewId &)

IMPORT_C TIntGetSystemDefaultView(TVwsViewId &aViewId)

Gets the system default view for the current screen device mode

Parameters

TVwsViewId & aViewIdThe 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 & aObserverAn 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 & aObserverAn 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 TIntNotifyNextActivation(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 & aViewIdThe view to monitor for activation.

NotifyNextActivation()

IMPORT_C TIntNotifyNextActivation()

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 TIntNotifyNextDeactivation(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 & aViewIdThe view to monitor for deactivation.

NotifyNextDeactivation()

IMPORT_C TIntNotifyNextDeactivation()

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

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 TIntRemoveView(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 & aViewIdThe view to be removed from the view server's list.

RequestCustomMessage(TDes8 &)

IMPORT_C TIntRequestCustomMessage(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 & aMessageBufPtrThe narrow descriptor for the custom message contents to be written to.

SetClientRequestTimeOut(TTimeIntervalMicroSeconds32)

IMPORT_C TIntSetClientRequestTimeOut(TTimeIntervalMicroSeconds32aDuration)

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 aDurationThe duration of the timeout, in microseconds.

SetCrossCheckUid(const TUid &)

IMPORT_C TIntSetCrossCheckUid(const TUid &aCrossCheckUid)

Parameters

const TUid & aCrossCheckUid

SetDefaultView(const TVwsViewId &, TInt)

IMPORT_C TIntSetDefaultView(const TVwsViewId &aViewId,
TIntaMode
)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 TIntSetDefaultView(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 TIntSetServerEventTimeOut(TTimeIntervalMicroSeconds32aDuration)

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 aDurationThe duration of the timeout, in microseconds.

SetSystemDefaultView(const TVwsViewId &, TInt)

IMPORT_C TIntSetSystemDefaultView(const TVwsViewId &aViewId,
TIntaMode
)

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 & aViewIdThe view to use as the system default view in the specified screen device mode
TInt aModeThe 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 TIntSetSystemDefaultView(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 & aViewIdThe view to use as the system default view in the default screen device mode

SetWindowBackgroundColor(const TRgb &)

IMPORT_C TIntSetWindowBackgroundColor(const TRgb &aBgColor)

Parameters

const TRgb & aBgColor

ShutdownViewServer()

IMPORT_C TIntShutdownViewServer()

Shut down the view server.

Establishes a connection to the view server if necessary.

StartApp(TUid)

IMPORT_C TIntStartApp(TUidaAppToStart)

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 aAppToStartThe Uid of the app that should be started.

StartViewServer(MVwsAppStarter &)

IMPORT_C TIntStartViewServer(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]