CBrCtlInterface Class Reference

API published in: S60 2nd Ed FP 3

Link against: browserengine.lib

Capability Information

Required Capabilities

None

Exceptions

NetworkServices capability is required for any operation that results in loading content from the network. For example, calling LoadUrlL() with a url parameter that refers to a network location requires NetworkServices capability if the content is not available from the cache or if the specified cache mode prevents loading the cached version.

#include <brctlinterface.h>

Detailed Description

The CBrCtlInterface class is the base class of the Browser Control API.

All clients of browser control must use this class. The functions defined in the CBrCtlInterface class implement basic Browser Control functionality. You can customize the Browser Control to extend its functionality by implementing additional interface classes in the host application. Examples of such classes are MBrCtlDataLoadSupplier, MBrCtlDialogsProvider, MBrCtlDialogsProvider etc.

Usage: 

  #include <BrCtlInterface.h>
  // Interface that provides dialogs used by the Browser Control.
  #include <BrCtlDialogsProvider.h>
  // Interface used to receive scrolling events.
  #include <BrCtlLayoutObserver.h>
  //Interface that provides a callback mechanism for receiving the
  //content of an embedded link or the content of a user-initiated
  //load request.
  #include <BrCtlLinkResolver.h>
  //Interface that handles requests to change the softkeys.
  #include <BrCtlSoftkeysObserver.h>
  //Interface that handles special load needs.
  #include <BrCtlSpecialLoadObserver.h>
  //Reserved for future use.
  #include <BrCtlWindowObserver.h>
  //Interface that passes download events from the
  //Download Manager through the Browser Control to the
  //host application.
  #include <BrCtlDownloadObserver.h>
  Enum Definition of the Browser Control API.
  #include <BrCtlDefs.h>


   The following types of things you can do with the Browser Control API.

 Creating a basic Browser Control
 Creating a Browser Control with observer interfaces
 Loading content
 Passing content incrementally
 Receiving load progress events
 Handling special load requests
 Customizing dialogs
 Specifying the softkeys
 Resolving links
 Customizing scroll bars
 Receiving change-of-state events

 @see S60 Platform: Browser Control API Developer's Guide Version 2.0
 
 
 @file BrCtlInterface.h
*

Public Member Functions
virtual  ~CBrCtlInterface ()
  Destructor.
virtual IMPORT_C void  HandleCommandL (TInt aCommand)=0
  Passes a command to the Browser Control.
virtual IMPORT_C TSize  ContentSize ()=0
  Return the display size that would be needed to see all the content.
virtual IMPORT_C void  SetBrowserSettingL (TUint aSetting, TUint aValue)=0
  Update a Browser Control setting.
virtual IMPORT_C TUint  BrowserSettingL (TUint aSetting)=0
  Get a setting from the Browser Control.
virtual IMPORT_C void  LoadDataL (const TDesC &aUrl, const TDesC8 &aData, const TDataType &aDataType, TUid aCharsetUid)=0
  Request the Browser Control to display the content of a buffer.
virtual IMPORT_C void  InitLoadDataL (const TDesC &aUrl, const TDataType &aDataType, TUid aCharsetUid, TUint aContentLength, MBrCtlDataLoadSupplier *aBrCtlDataLoadSupplier, MBrCtlDataLoadConsumer **aBrCtlDataLoadConsumer)=0
  Request the Browser Control to display content incrementaly.
virtual IMPORT_C void  LoadUrlL (const TDesC &aUrl, TInt aApId=-1, TBrCtlDefs::TBrCtlCacheMode aBrCtlCacheMode=TBrCtlDefs::ECacheModeNormal)=0
  Request the Browser Control to load a url.
virtual IMPORT_C void  LoadFileL (const TDesC &aFileName)=0
  Request the Browser Control to load and display a file from the file system.
virtual IMPORT_C void  LoadFileL (RFile &aFileHandle)=0
  Request the Browser Control to load and display a file from the file system.
virtual IMPORT_C RPointerArray<
TBrCtlWmlServiceOption > *  		WMLOptionMenuItemsL ()=0
  Return the WML Options for the current page.
virtual IMPORT_C void  AddOptionMenuItemsL (CEikMenuPane &aMenuPane, TInt aResourceId, TInt aAfter=-1)=0
  Request the Browser Control to add its own options to the option menu.
virtual IMPORT_C TUint  ClearCache ()=0
  Request the Browser Control to clear the cache.
virtual IMPORT_C TBool  IsUrlInCache (TDesC &aUrl)=0
  Ask the Browser Control if a URL is in cache.
virtual IMPORT_C TInt  ClearItemInCache (TDesC &aUrl)=0
  Ask the Browser Control to clear a URL from the cache.
virtual IMPORT_C HBufC *  PageInfoLC (TBrCtlDefs::TBrCtlPageInfo aBrCtlPageInfo)=0
  Request the Browser Control to return info about the page.
virtual IMPORT_C TBool  NavigationAvailable (TBrCtlDefs::TBrCtlNavigationDirection aDirection)=0
  From CBrCtlInterface Query the Browser Control if there is a previous or next (depending on aDirection) element in history stack.
virtual IMPORT_C TUint16  SaveToFileL (const TDesC &aFileName)=0
  Request the Browser Control to save the current content to a file.
virtual IMPORT_C const TCertInfo *  CertInfo ()=0
  Request the Browser Control to pass the server's certificate info for the current page.
virtual IMPORT_C void  AddLoadEventObserverL (MBrCtlLoadEventObserver *aBrCtlLoadEventObserver)=0
  Request the Browser Control to register for load events.
virtual IMPORT_C void  RemoveLoadEventObserver (MBrCtlLoadEventObserver *aBrCtlLoadEventObserver)=0
  Request the Browser Control to unregister for load events.
virtual IMPORT_C TInt  ImageCountL ()=0
  Return the number of images in the current page.
virtual IMPORT_C TBrCtlDefs::TBrCtlElementType  FocusedElementType ()=0
  Returns the focused element.
virtual IMPORT_C void  AddStateChangeObserverL (MBrCtlStateChangeObserver *aBrCtlStateChangeObserver)=0
  Register an observer for state changes.
virtual IMPORT_C void  RemoveStateChangeObserver (MBrCtlStateChangeObserver *aBrCtlStateChangeObserver)=0
  Unregister an observer for state changes.
virtual IMPORT_C HBufC *  VersionInfoLC (TBrCtlDefs::TBrCtlVersionInfo aVersionInfo)=0
  Request the Browser Control to return info about the Browser Control version.
virtual IMPORT_C void  SetSelfDownloadContentTypesL (TDesC &aContentTypes)=0
  Pass a list of content types to the Browser Control.
virtual IMPORT_C void  SetParamL (TBrCtlDefs::TBrCtlParams aParam, const TDesC &aValue)=0
  Update a Browser Control parameter.
virtual IMPORT_C void  LoadSavedPageL (const TDesC &aUid, TDesC &aSavedPageBuffer)=0
  Request the Browser Control to load a saved page.
virtual IMPORT_C RArray< TUint > *  ZoomLevels () const =0
  Return the zoom levels index.
virtual IMPORT_C int  FindKeyword (const TDesC &aKeyword)=0
  Perform the incremental find operation.
virtual IMPORT_C TBrCtlDefs::TBrCtlFindResponse  FindKeywordAgain (TBool aFowardDirection)=0
  Continue the incremental find operation.
virtual IMPORT_C const RPointerArray<
TBrCtlSubscribeTo > &  		SubscribeToMenuItemsL ()=0
  Return information about the linked feeds in the current page - used to build a "Subscribe to" submenu.
virtual IMPORT_C TSize  MinimumSize ()=0
  From CCoeControl Return the minimum size the Browser Control can use.
virtual IMPORT_C TKeyResponse  OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)=0
  From CCoeControl Pass key events to the Browser Control.
virtual IMPORT_C void  SetFocus (TBool aFocus, TDrawNow aDrawNow=ENoDrawNow)=0
  From CCoeControl Sets that the Browser Control has keyboard focus.
virtual IMPORT_C TBool  OkToExit ()=0
virtual IMPORT_C void  HandleDownloadCommandL (TUint16 aTransId, TBrCtlDefs::TBrCtlDownloadCmd aCommand)=0
  This method calls to download manager in order to send the commands (EDownloadCmdPause,DownloadCmdResume, EDownloadCmdCancel, EDownloadCmdMarkAsProgressive, EDownloadCmdMarkAsNotProgressive ).
virtual IMPORT_C CGulIcon *  GetBitmapData (const TDesC &aUrl, TBrCtlDefs::TBrCtlBitmapInfo aBitmapInfo)=0
  Request icon for the given url.
virtual IMPORT_C void  AddCommandObserverL (MBrCtlCommandObserver *aBrCtlCommandObserver)=0
  Register a client command interface for the browser engine.
virtual IMPORT_C void  RemoveCommandObserver (MBrCtlCommandObserver *aBrCtlCommandObserver)=0
  Unregister a client command interface for the browser engine.
virtual IMPORT_C MWidgetExtension *  CreateWidgetExtensionL (MWidgetCallback &aWidgetCallback)=0
  Unregister a client command interface for the browser engine.
virtual IMPORT_C TBrCtlImageCarrier *  FocusedImageLC ()=0
  Get information about the focused image.

Constructor & Destructor Documentation

virtual CBrCtlInterface::~CBrCtlInterface (   )  [inline, virtual]
 

Destructor.

Member Function Documentation

virtual IMPORT_C void CBrCtlInterface::AddCommandObserverL (  MBrCtlCommandObserver *  aBrCtlCommandObserver  )  [pure virtual]
 

Register a client command interface for the browser engine.

Parameters:
The  observer to register
Returns:
void
virtual IMPORT_C void CBrCtlInterface::AddLoadEventObserverL (  MBrCtlLoadEventObserver *  aBrCtlLoadEventObserver  )  [pure virtual]
 

Request the Browser Control to register for load events.

Parameters:
aBrCtlLoadEventObserver  A load events observer to add
Returns:
void Call this function immediately after creating the Browser Control. For multiple registrations, the host application may call this function more than once. Observers must unregister before deleting the Browser Control.
virtual IMPORT_C void CBrCtlInterface::AddOptionMenuItemsL (  CEikMenuPane &  aMenuPane,
TInt  aResourceId,
TInt  aAfter = -1
)  [pure virtual]
 

Request the Browser Control to add its own options to the option menu.

Parameters:
aMenuPane  Handle of the menu that will contain the options
aResourceId  The resource ID of the menu
aAfter  WML options should be added after that index
Returns:
void
virtual IMPORT_C void CBrCtlInterface::AddStateChangeObserverL (  MBrCtlStateChangeObserver *  aBrCtlStateChangeObserver  )  [pure virtual]
 

Register an observer for state changes.

Parameters:
aBrCtlStateChangeObserver  The observer to register
Returns:
void The Observer must unregister before deleting the Browser Control.
virtual IMPORT_C TUint CBrCtlInterface::BrowserSettingL (  TUint  aSetting  )  [pure virtual]
 

Get a setting from the Browser Control.

Parameters:
aSetting  The setting to get
Leave:
KErrArgument if the value of aSetting is out of range.
Returns:
The value of the setting
virtual IMPORT_C const TCertInfo* CBrCtlInterface::CertInfo (   )  [pure virtual]
 

Request the Browser Control to pass the server's certificate info for the current page.

Returns:
Certificate info of the server of the current page
virtual IMPORT_C TUint CBrCtlInterface::ClearCache (   )  [pure virtual]
 

Request the Browser Control to clear the cache.

Returns:
The number of bytes that were freed from cache.
virtual IMPORT_C TInt CBrCtlInterface::ClearItemInCache (  TDesC &  aUrl  )  [pure virtual]
 

Ask the Browser Control to clear a URL from the cache.

Parameters:
aUrl  The Url
Returns:
KErrNone if the URL is cleared from the cache Error message is the URL has not been cleared.
virtual IMPORT_C TSize CBrCtlInterface::ContentSize (   )  [pure virtual]
 

Return the display size that would be needed to see all the content.

Returns:
The display size that would be needed to see all the content
virtual IMPORT_C MWidgetExtension* CBrCtlInterface::CreateWidgetExtensionL (  MWidgetCallback &  aWidgetCallback  )  [pure virtual]
 

Unregister a client command interface for the browser engine.

Parameters:
The  observer to unregister
Returns:
void
virtual IMPORT_C int CBrCtlInterface::FindKeyword (  const TDesC &  aKeyword  )  [pure virtual]
 

Perform the incremental find operation.

Parameters:
aKeyword  String to be find.
Returns:
TBrCtlFindResponse
virtual IMPORT_C TBrCtlDefs::TBrCtlFindResponse CBrCtlInterface::FindKeywordAgain (  TBool  aFowardDirection  )  [pure virtual]
 

Continue the incremental find operation.

Parameters:
aFowardDirection  TRUE if search is in forword direction. For backword direction, it is FALSE.
Returns:
TBrCtlFindResponse
Attention:
Method that is called when the user searches for the next keyword in the doc.
virtual IMPORT_C TBrCtlDefs::TBrCtlElementType CBrCtlInterface::FocusedElementType (   )  [pure virtual]
 

Returns the focused element.

Returns:
The type of the focused element The host application may need to perform special processing, such as updating the softkeys, when a specific element has the focus.
virtual IMPORT_C TBrCtlImageCarrier* CBrCtlInterface::FocusedImageLC (   )  [pure virtual]
 

Get information about the focused image.

The function leaves if the focus is not on an image

Parameters:
@return  The requested information
virtual IMPORT_C CGulIcon* CBrCtlInterface::GetBitmapData (  const TDesC &  aUrl,
TBrCtlDefs::TBrCtlBitmapInfo  aBitmapInfo
)  [pure virtual]
 

Request icon for the given url.

Parameters:
aUrl  url to a favicon or a page
aBitmapInfo  info on whether to retun a favicon or a page icon
Returns:
favion icon or page icon
virtual IMPORT_C void CBrCtlInterface::HandleCommandL (  TInt  aCommand  )  [pure virtual]
 

Passes a command to the Browser Control.

Parameters:
aCommand  The command that the Browser Control should process
Returns:
void
See also:
TBrCtlCommands, For a complete list of commands,
virtual IMPORT_C void CBrCtlInterface::HandleDownloadCommandL (  TUint16  aTransId,
TBrCtlDefs::TBrCtlDownloadCmd  aCommand
)  [pure virtual]
 

This method calls to download manager in order to send the commands (EDownloadCmdPause,DownloadCmdResume, EDownloadCmdCancel, EDownloadCmdMarkAsProgressive, EDownloadCmdMarkAsNotProgressive ).

Parameters:
aCommand  The command that the Browser Control should process
aTransId  The transaction Id associated with this command
Returns:
void
virtual IMPORT_C TInt CBrCtlInterface::ImageCountL (   )  [pure virtual]
 

Return the number of images in the current page.

Parameters:
@return  The number of images in the current page
virtual IMPORT_C void CBrCtlInterface::InitLoadDataL (  const TDesC &  aUrl,
const TDataType &  aDataType,
TUid  aCharsetUid,
TUint  aContentLength,
MBrCtlDataLoadSupplier *  aBrCtlDataLoadSupplier,
MBrCtlDataLoadConsumer **  aBrCtlDataLoadConsumer
)  [pure virtual]
 

Request the Browser Control to display content incrementaly.

Parameters:
aUrl  A url that refers to the data. If a url scheme is used, it must be "data:"
aDataType  The data type of the data
aCharsetUid  The UID of the character converter of the content's charset 0 assumed Latin-1
aContentLength  The length of the content.
aBrCtlDataLoadSupplier  A callback interface to stop passing data if an error occured in the Browser Control
aBrCtlDataLoadConsumer  A callback interface returned by the browser. Data should be passed to that interface
Returns:
void If you use this function, the Browser Control does not keep track of the history.If the content type of the data is not markup, Browser Control uses the Special Load Observer to pass the content back to the Host Application. The Special Load Observer uses the Document Handler to send the content to the proper application.
virtual IMPORT_C TBool CBrCtlInterface::IsUrlInCache (  TDesC &  aUrl  )  [pure virtual]
 

Ask the Browser Control if a URL is in cache.

Parameters:
aUrl  The Url
Returns:
ETrue, if a specific Url is in cache EFalse if the URL is not in the cache
virtual IMPORT_C void CBrCtlInterface::LoadDataL (  const TDesC &  aUrl,
const TDesC8 &  aData,
const TDataType &  aDataType,
TUid  aCharsetUid
)  [pure virtual]
 

Request the Browser Control to display the content of a buffer.

Parameters:
aUrl  A url that refers to the data. If a url scheme is used, it must be "data:"
aData  The content to display. Browser Control does not take ownership
aDataType  The data type of the data
aCharsetUid  The UID of the character converter of the content's charset 0 assumed Latin-1
Returns:
void
Attention:
If you use this function, the Browser Control does not keep track of the history. If the data is not markup, Browser Control uses the Special Load Observer to pass the content back to the Host Application. The Special Load Observer uses the Document Handler to send the content to the proper application.
virtual IMPORT_C void CBrCtlInterface::LoadFileL (  RFile &  aFileHandle  )  [pure virtual]
 

Request the Browser Control to load and display a file from the file system.

Parameters:
aFileHandle  The handle of the file
Returns:
void
virtual IMPORT_C void CBrCtlInterface::LoadFileL (  const TDesC &  aFileName  )  [pure virtual]
 

Request the Browser Control to load and display a file from the file system.

Parameters:
aFileName  The name of the file
Returns:
void
virtual IMPORT_C void CBrCtlInterface::LoadSavedPageL (  const TDesC &  aUid,
TDesC &  aSavedPageBuffer
)  [pure virtual]
 

Request the Browser Control to load a saved page.

Parameters:
aUid  a unique identifier for the saved page
aSavedPageBuffer  buffer which contains the content of the saved page
Returns:
void
virtual IMPORT_C void CBrCtlInterface::LoadUrlL (  const TDesC &  aUrl,
TInt  aApId = -1,
TBrCtlDefs::TBrCtlCacheMode  aBrCtlCacheMode = TBrCtlDefs::ECacheModeNormal
)  [pure virtual]
 

Request the Browser Control to load a url.

Parameters:
aUrl  The url to load
aApId  The Access Point Id to use
aCacheMode  The cache mode to use. Values: One of the following: ECacheModeNormal ECacheModeHistory ECacheModeNoCache ECacheModeOnlyCache
See also:
For a description of each of these values, see TBrCtlCacheMode
Returns:
void
virtual IMPORT_C TSize CBrCtlInterface::MinimumSize (   )  [pure virtual]
 

From CCoeControl Return the minimum size the Browser Control can use.

Returns:
The minimum size that the Browser Control can use.
Attention:
This function is inherited from the Symbian CCoeControl class.
virtual IMPORT_C TBool CBrCtlInterface::NavigationAvailable (  TBrCtlDefs::TBrCtlNavigationDirection  aDirection  )  [pure virtual]
 

From CBrCtlInterface Query the Browser Control if there is a previous or next (depending on aDirection) element in history stack.

Parameters:
aDirection  ENavigationBack if you wish to query whether there is a previous element in the history stack. ENavigationForward if you wish to query whether there is a subsequent element in the history stack.
Returns:
ETrue if can go aDirection, EFalse otherwise
virtual IMPORT_C TKeyResponse CBrCtlInterface::OfferKeyEventL (  const TKeyEvent &  aKeyEvent,
TEventCode  aType
)  [pure virtual]
 

From CCoeControl Pass key events to the Browser Control.

Parameters:
aKeyEvent  The key event
aType  The key code
Returns:
If the Browser Control consumed the key event or not
Attention:
This function is inherited from the Symbian CCoeControl class.
virtual IMPORT_C TBool CBrCtlInterface::OkToExit (   )  [pure virtual]
 
virtual IMPORT_C HBufC* CBrCtlInterface::PageInfoLC (  TBrCtlDefs::TBrCtlPageInfo  aBrCtlPageInfo  )  [pure virtual]
 

Request the Browser Control to return info about the page.

The info is returned on the Cleanup Stack.

Parameters:
aBrCtlPageInfo  The type of requested info
Returns:
A descriptor containing the requested page info
Attention:
The information is returned on the Cleanup stack.
virtual IMPORT_C void CBrCtlInterface::RemoveCommandObserver (  MBrCtlCommandObserver *  aBrCtlCommandObserver  )  [pure virtual]
 

Unregister a client command interface for the browser engine.

Parameters:
The  observer to unregister
Returns:
void
virtual IMPORT_C void CBrCtlInterface::RemoveLoadEventObserver (  MBrCtlLoadEventObserver *  aBrCtlLoadEventObserver  )  [pure virtual]
 

Request the Browser Control to unregister for load events.

Parameters:
aBrCtlLoadEventObserver  A load events observer to remove
Returns:
void Call this function for each Load Observer that was previously registered.
virtual IMPORT_C void CBrCtlInterface::RemoveStateChangeObserver (  MBrCtlStateChangeObserver *  aBrCtlStateChangeObserver  )  [pure virtual]
 

Unregister an observer for state changes.

Parameters:
The  observer to unregister
Returns:
void
virtual IMPORT_C TUint16 CBrCtlInterface::SaveToFileL (  const TDesC &  aFileName  )  [pure virtual]
 

Request the Browser Control to save the current content to a file.

Parameters:
aFileName  The name of the file to use for saving the content
Returns:
The number of bytes in the saved file
virtual IMPORT_C void CBrCtlInterface::SetBrowserSettingL (  TUint  aSetting,
TUint  aValue
)  [pure virtual]
 

Update a Browser Control setting.

Parameters:
aSetting  The setting to update
aValue  The new value of the setting
Leave:
KErrArgument if the value of aSetting is out of range.
Returns:
void
virtual IMPORT_C void CBrCtlInterface::SetFocus (  TBool  aFocus,
TDrawNow  aDrawNow = ENoDrawNow
)  [pure virtual]
 

From CCoeControl Sets that the Browser Control has keyboard focus.

Parameters:
aFocus  If the Browser Control gets or loses focus
ENoDrawNow  If the Browser Control should redraw itself as result of focus change
Returns:
void
Attention:
This function is inherited from the Symbian CCoeControl class.
virtual IMPORT_C void CBrCtlInterface::SetParamL (  TBrCtlDefs::TBrCtlParams  aParam,
const TDesC &  aValue
)  [pure virtual]
 

Update a Browser Control parameter.

consequent calls with the same aParam will replace the value, and not append to it.

Parameters:
aParam  The parameter to update
aValue  The new value of the parameter EParamsSelfDownoadableTypes: Pass a list of content types to the Browser Control. These content types will not be using the download manager. The list must be separated by ';' e.g. "text/html;text/wml"
EParamsRequestHeaders: Pass a list of headers that the Browser Control. These headers will be added to each request. The list must be separated by ''. The header name and value must be separated by ':' e.g. "x-myheader: myvalue\rx-myotherheader: myothervalue"
Returns:
void
virtual IMPORT_C void CBrCtlInterface::SetSelfDownloadContentTypesL (  TDesC &  aContentTypes  )  [pure virtual]
 

Pass a list of content types to the Browser Control.

These content types will not be using the download manager. The list must be separated by ';' e.g. "text/html;text/wml"

Parameters:
aContentTypes  The content types that should not use Download Manager
Returns:
void
Deprecated:
This function is deprecated. Use the EParamsSelfDownloadableTypes parameter of the SetParamL function instead.
virtual IMPORT_C const RPointerArray<TBrCtlSubscribeTo>& CBrCtlInterface::SubscribeToMenuItemsL (   )  [pure virtual]
 

Return information about the linked feeds in the current page - used to build a "Subscribe to" submenu.

Returns:
Information about the linked feeds in the current page. The caller adopts the result.
virtual IMPORT_C HBufC* CBrCtlInterface::VersionInfoLC (  TBrCtlDefs::TBrCtlVersionInfo  aVersionInfo  )  [pure virtual]
 

Request the Browser Control to return info about the Browser Control version.

The info is returned on the Cleanup Stack.

Parameters:
aVersionInfo  The type of requested info
Returns:
A descriptor containing the requested page info
Attention:
The information is returned on the Cleanup Stack.
virtual IMPORT_C RPointerArray<TBrCtlWmlServiceOption>* CBrCtlInterface::WMLOptionMenuItemsL (   )  [pure virtual]
 

Return the WML Options for the current page.

Parameters:
@return  The WML Options for the current page
virtual IMPORT_C RArray<TUint>* CBrCtlInterface::ZoomLevels (   )  const [pure virtual]
 

Return the zoom levels index.

Returns:
The zoom levels array.
The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2008
Back to top